TL;DR -- Add structure only when something hurts, not because a guide tells you to. This page lists symptoms you can notice yourself while working with your AI, and what to do about each one. Already have a project? Add AGENTS.md first, then reorganize one piece at a time. Start over from scratch only when the old technology is dead or the language changes.
Never add structure preemptively. If you are not feeling the pain, you do not need the cure. Structure that nobody maintains is worse than no structure at all.
When you do add structure: one step at a time. Add one change, see if it helps, then decide if you need more. Do not jump from Stage 1 to Stage 3 in one session.
Every trigger below is something you can notice yourself: a moment in your daily work, not an architecture judgment. You do not need to know what "business logic" or "coupling" means. If a symptom happens once, ignore it. If it keeps happening, apply the fix in the right column.
Not sure which symptoms your project has? Let your AI diagnose it:
"Read AGENTS.md and docs/todo.md, then look at the codebase and the recent git history. Check for these problems: files that are hard to find, one change that forced edits in many places, rules from AGENTS.md that were violated, decisions that are not written down anywhere. Report what you find with examples, tell me which stage of structure the project needs next, and why. Do not change anything."
If you already have a codebase and want to add codeOath structure, read the trigger tables below and find the symptoms that match your current pain. That tells you which stage to aim for. You do not have to start at Stage 1 if your project already has the problems of Stage 2 or 3.
- Start with Stage 1 regardless: add
AGENTS.md(with NOT field) anddocs/todo.md. Low effort and helps immediately. - Do not reorganize code yet. First document what exists: what does each file do? What depends on what?
- When you feel the pain (see triggers below), introduce Stage 2 concepts one at a time. Start in the area that hurts most, not everywhere at once.
- Build the new structure next to the old one and move one piece at a time, then remove the old part once nothing uses it anymore. This is the default for most projects. (Developers call this the Strangler Fig approach.)
Ask your AI to help with the migration:
"Read my AGENTS.md and understand the project. I want to migrate to a domain/adapters structure, one piece at a time, without rewriting everything at once. Pick the one file where core logic and database/file/API code are most tangled. Extract the core logic into domain/ and the rest into adapters/. Wire them together in main. Fix imports. Run the tests. Then stop and let me review before moving to the next file."
For the detailed step-by-step migration pattern (shim files, one-file-at-a-time commits, verification), see How to Migrate Your Existing Code.
Sometimes migrating piece by piece costs more than it saves. Consider a clean rewrite when:
- Language change: You are moving from one language to another (e.g., C to Python). The old code is reference material, not a migration source.
- Most of the code must change: If you spend more time building bridges between old and new than on the actual restructuring, piece-by-piece migration is creating more overhead than it prevents.
- Fundamental security flaw: The architecture itself is compromised (e.g., secrets baked into the data model, no separation between user contexts). Patching cannot fix a broken foundation.
- No tests and no understanding: If nobody understands what the code does and there are no tests to verify behavior, migrating preserves bugs you cannot see.
- Dead technology: The framework or runtime itself is no longer maintained (e.g., AngularJS 1.x, Python 2, abandoned libraries). Migrating piece by piece inside a dying ecosystem means building bridges that will collapse anyway.
Even when rewriting: start with AGENTS.md. Define the project, the rules, and the structure before writing the first line. Keep the old codebase as read-only reference, do not delete it until the new version is verified. Do not try to replicate the old system 1:1; use the rewrite to fix the problems that caused the rewrite. A rewrite is not a license to build the system you always dreamed of. Fix what caused the rewrite, nothing more.
From Nothing to Stage 1
| When you notice... | Introduce... |
|---|---|
| You start a project and want AI to help | AGENTS.md with project definition |
| You forget what you planned to do next | docs/todo.md |
| Your AI suggests features you never asked for | NOT field in AGENTS.md |
From Stage 1 to Stage 2
| When you notice... | Introduce... |
|---|---|
| You told your AI where things go, and it still puts new files elsewhere | domain/ and adapters/ separation |
| You ask "why did we do it this way?" and nobody has an answer | docs/decisions.md |
| You change one small thing and something unrelated stops working | Split by layer (domain vs. adapter) |
| Two files always have to change together, never one alone | Move the shared logic into one place |
| You avoid touching working code because you cannot tell if it still works afterwards | Ports and tests in domain/ |
| Your AI asks the same questions about scope every session | Architecture rules in AGENTS.md |
| Resolved items in todo.md are longer than open items | docs/todo_archive.md |
| You keep forgetting to check docs or dependencies | Routines section in todo.md |
From Stage 2 to Stage 3
| When you notice... | Introduce... |
|---|---|
AGENTS.md is over 80 lines |
.claude/rules/ with path-specific loading |
| You corrected your AI about the same rule twice, and it broke it again | Import linter or architecture check |
| A second person or a second AI tool joins, and the code starts looking inconsistent | Pre-commit hooks, branching strategy |
| Your main file reads like a step-by-step script that keeps growing | application/ layer |
adapters/ has become a junk drawer (database, bot, exports all mixed) |
adapters/in/ and adapters/out/ |
| Your AI reads files it should not | .claude/settings.json deny rules |
| You want to publish or deploy and worry something unsafe slips through | Security checklist |
| Files look different depending on the week they were written | Automated linting and formatting |
The project description in AGENTS.md no longer fits on one screen |
Extract to docs/definition.md |
| The project runs on its own (service, bot, or scheduled job) and only you know how to restart it | docs/operations.md |
| When you notice... | Consider... |
|---|---|
| Rules that are right in one part of the project are wrong in another | Splitting into separate projects |
| Finishing one feature keeps blocking work on another | Feature-sliced architecture |
| Modules need hard boundaries | Modular monolith |
| More than 10 architecture decisions per month | Revisit the project definition |
| The project definition feels wrong | Update it deliberately (Layer 1 change) |
docs/todo.md keeps growing |
Scope is too big, prioritize ruthlessly |
The core rule works in both directions. Structure that only creates work and no longer prevents pain should go: a port that never got a second adapter, routines nobody runs, an application/ layer that only passes calls through. Remove it like you added it: one piece at a time, commit in between.