[Prompt Engineering & AI] How to Boost Your Architecture Refactoring with Claude Code

Generative AI has revolutionized our development practices, but its potential remains underutilized in software architecture. One method I successfully use in my Clean Architecture projects involves guiding Claude Code (or any code-centric LLM) through a user story tracking file… generated by the AI itself!

The Trick: Ask Claude Code to Create a Tracking File for Your Architecture User Stories

It all starts with a very simple, yet incredibly effective prompt:

Act as a software architect and analyse the project to identify architecture issues that need to be resolved in my clean architecture. Then create a USER_STORIES_ARCHITECTURE.md file with your plan. Add it to the tracking system to help us follow the plan.

Claude Code then analyzes your repository and produces a structured file to drive the transformation. Here's an example extracted from a real project:

# Architecture Improvement User Stories ## How AI must use this document - read the user stories to understand the architectural improvements needed for the ==MY_APP_NAME== application - implement the changes as described in the user stories - try to compile the code after each change to ensure it works - test the application to verify that the changes do not break existing functionality - update the status of each user story in this document as you progress - update CURRENT_STATUS in the Tracking Legend section to reflect the current state of all user stories - commit changes to the repository with appropriate messages ## Overview This document outlines the architectural improvements needed for the ==MY_APP_NAME== application, organized as user stories with a tracking system to monitor progress. ## Tracking Legend - 🔴 **Not Started**: Work has not begun - 🟡 **In Progress**: Currently being worked on - 🟢 **Completed**: Fully implemented and tested - 🔵 **Blocked**: Cannot proceed due to dependencies - ⚫ **Cancelled**: Decided not to implement - CURRENT_STATUS: ARCH-001 is **In Progress**. All other stories are in the **Not Started** state. ## Epic 1: Clean Architecture Compliance *Goal: Ensure proper layer separation and dependency flow* ### 🟡 ARCH-001: Remove Infrastructure Dependency from Application Layer **As an** architect **I want to** remove the Infrastructure project reference from Application project **So that** we maintain proper dependency inversion and clean architecture principles **Acceptance Criteria:** - [ ] Application.csproj no longer references Infrastructure.csproj - [ ] All infrastructure concerns are abstracted behind interfaces - [ ] Application layer only depends on Domain layer - [ ] All tests pass after refactoring **Effort:** Large (3-5 days) **Priority:** Critical **Dependencies:** None

Why Does It Work?

The key to success: the “How AI must use this document” section. We explicitly explain to the AI how to behave at each iteration:

This user manual acts as an operational guide for the AI, ensuring consistent and reproducible cycles, even during long refactoring or continuous improvement sessions.

In Practice: An AI That Structures, Prioritizes, and Executes

Once this file is populated, you simply provide it to Claude Code. The AI then follows each story, goes through the steps one by one, updates the tracking, and enriches the product with each commit. Result: fine-grained management of your architecture projects, with clear history, statuses, priorities… and refactoring that actually moves forward.

Key Takeaways

I use this method daily – it's a game-changer for AI-driven software architecture transformation.

💬 Have you tested this kind of workflow with Claude Code, ChatGPT, or others? Curious to hear your feedback or tips!