🏗️ Project architecture
Structure a project built to last: folders, modules, separation of responsibilities, stack selection, documented decisions, and an incremental growth strategy.
1 📁 A sensible folder structure
Canonical folder structure—each directory has a single responsibility
The folder structure is the project’s first contract. It tells Claude (and any contributor) what goes where before they read a line of code.
my-project/
├── src/
│ ├── components/ # UI e lógica de apresentação
│ ├── lib/ # Utilitários puros
│ ├── types/ # TypeScript interfaces
│ └── data/ # Artefatos JSON gerados
├── scripts/
│ ├── aggregate.ts # Data pipeline
│ └── setup.ts # Setup único
├── docs/
│ ├── adr/ # Architecture Decision Records
│ └── CHANGELOG.md
├── tests/
├── CLAUDE.md # Instruções do agente
├── package.json
└── .env.example # Template de variáveis✓ Do it
- • Each folder has a single responsibility
- • Lowercase names with no spaces
- • README.md or index.ts in each folder
- • scripts/ separate from src/
- • docs/ for decisions and changelog
✗ Avoid
- • Folder
misc/orstuff/ - • Giant utils folder with 50 files
- • Mixing build scripts with code
- • Files in the root with no clear purpose
- • Nesting deeper than 4 levels
Practical tip
Show the folder structure in CLAUDE.md with tree -L 2. Claude understands the project without having to explore files one by one.
2 🔩 Separation of Concerns
Each module should have a reason to exist and a reason to change. When this isn't respected, any change can cause unexpected effects throughout the system.
How separation evolves in a real project
Everything in one file
Normal at the start. An index.ts with fetch, logic, and rendering mixed together. It works, but doesn't scale well.
Layer separation
Data fetching in lib/api.ts, types in types/, isolated React components. Each part is testable.
Modules with defined interfaces
Each module exports a public interface. The internal implementation can change without breaking other modules. Claude modifies one module at a time.
✓ Well-separated module
- • One clear responsibility
- • Minimal public interface
- • Explicit dependencies (parameters)
- • Independently testable
- • Can be replaced without a cascade
✗ Tightly coupled module
- • Reads global variables directly
- • Performs I/O and logic in the same place
- • Imports half the codebase
- • Requires a real database for testing
- • A change breaks 5 other things
Rule of thumb
If you need to explain more than two things a module does, it probably does too much. Ask Claude: “Identify responsibilities mixed together in this file.”
3 🧱 Stack selection
A stack is a long-term decision. Switching runtimes midway through a project is costly. Choosing well at the start saves months of work.
Criteria for choosing a stack for projects with Claude Code
✅ Technical criteria
- • Performance suited to the problem
- • Mature package ecosystem
- • Native TypeScript or easy to add
- • Integrated test support
🤖 Criteria for Claude
- • Popular stack = Claude knows it well
- • Well-indexed public docs
- • Plenty of examples in the training
- • Errors with clear messages
# ADR-001: Escolha de runtime — Bun
## Status: Aceito (2026-05-01)
## Contexto
Projeto precisa de: TypeScript nativo, execução rápida
de scripts, bundler integrado, compatibilidade Node.js.
## Opções consideradas
- Node.js + tsx: familiar, mas startup lento
- Deno: boa DX, mas ecossistema menor
- Bun: startup 3x mais rápido, bundler nativo, TS out-of-box
## Decisão
Usar Bun como runtime principal.
## Consequências
+ Scripts de build ~200ms (vs ~600ms com Node)
+ Sem configuração adicional de TypeScript
- Alguns pacotes npm com compatibilidade parcial
- Equipe precisa instalar Bun (curl ... | bash)Stacks with the best Claude support in 2026
TypeScript/Node/Bun, React/Next.js, Python/FastAPI, Go stdlib. Niche or very new frameworks get weaker support — prefer mainstream options when the choice makes no difference.
4 📝 Document decisions with ADRs
Architecture Decision Records (ADRs) are short documents that record why a decision was made, which options were considered, and what the expected consequences are.
Context
Why did this decision need to be made? What was the problem or opportunity?
Options
Which alternatives were evaluated? Why was each one accepted or rejected?
Consequences
What changes after the decision? Expected positive and negative benefits.
Watch out for outdated ADRs
An ADR that no longer reflects reality is worse than no ADR. Claude will follow outdated instructions. Review ADRs whenever the decision changes — even if it’s just to mark “Superseded by ADR-007.”
5 🌱 Start small and grow
Projects with Claude evolve quickly. The trap is planning a complex architecture before validating the core. Start with a walking skeleton—details later.
Healthy growth cycle
Week 1 — Functional core
One file that does the most important thing. No premature abstraction. Validates the main hypothesis.
Weeks 2-4 — Separation
Extract modules as patterns emerge. Add tests for the validated core.
Month 2+ — Scaling
Add features on a solid foundation. Architecture established organically — not designed in a vacuum.
YAGNI with Claude
"You Aren't Gonna Need It" is doubly important with LLMs. Claude can quickly generate elaborate abstractions — but abstractions created too early lead to invisible technical debt. Always ask for the simplest solution first.
6 🔭 Long-Term Vision
Projects survive when they have maintenance rituals, not just features. What you do every week matters more than the initial architecture.
✓ Healthy rituals
- • Weekly review of TODOs/FIXMEs
- • CHANGELOG updated with every version
- • Dependencies updated monthly
- • CLAUDE.md reviewed quarterly
- • Coverage metrics monitored
✗ Signs of an unhealthy project
- • CHANGELOG abandoned at V0.1
- • Dependencies 2 years out of date
- • CLAUDE.md was never updated
- • TODOs accumulating without cleanup
- • No one knows why X exists
📋 Module summary
- • Folder structure with a single responsibility
- • Separation of responsibilities by module
- • Criteria for choosing a stack
- • ADRs as decision memory
- • Incremental growth with YAGNI
- • Healthy maintenance rituals
- • Create your project's folder structure
- • Write the first stack ADR
- • Define each module's responsibilities
- • Configure CLAUDE.md with the folder map