tools-only Software Development: Typical Structure
The directory layout that works for software development projects.
Core Structure
[project-name]/
├── CLAUDE.md # Project context, coding standards, command reference
├── README.md # Human-facing workflow guide
│
├── context/ # Project context (from intake, living)
│ ├── requirements.md # Purpose, users, success criteria
│ ├── decisions.md # Key decisions with rationale
│ ├── constraints.md # Technical, timeline, organizational limits
│ └── questions.md # Open questions backlog
│
├── docs/ # The context ecosystem
│ ├── development/ # Technical documentation
│ │ ├── current-architecture.md # LIVING — system architecture (updated by /capture-learnings)
│ │ ├── current-security-assessment.md # LIVING — security posture
│ │ ├── current-test-strategy.md # LIVING — test philosophy, coverage, invariants
│ │ ├── adr/ # Architecture Decision Records (permanent)
│ │ │ ├── ADR-001-*.md
│ │ │ └── ...
│ │ ├── guides/ # Repeatable procedures (permanent)
│ │ │ └── *.md
│ │ ├── sdd-[TICKET]-[PR#].md # ACTIVE — Software Design Doc (current work)
│ │ └── archive/ # Completed SDDs, target docs
│ │
│ ├── planning/ # Implementation tracking
│ │ ├── plan-[TICKET]-[PR#].md # ACTIVE — Implementation plan (current work)
│ │ ├── pr-tracking-[TICKET].md # ACTIVE — PR breakdown for multi-PR issues
│ │ └── archive/ # Completed plans, tracking docs
│ │
│ ├── requirements/ # What to build
│ │ ├── current-features.md # LIVING — feature inventory
│ │ ├── target-features-[TICKET].md # ACTIVE — desired feature state for issue
│ │ └── archive/ # Completed target docs
│ │
│ ├── design/ # Visual and UX references (optional)
│ │ ├── visual-guide.md # Extracted design specs
│ │ └── screenshots/ # Reference images
│ │
│ └── evolution/ # Process improvement (fed by /record, analyzed by /evolve)
│ ├── session-records.md # Accumulated retrospective entries
│ └── evolution-proposal-*.md # Maturation proposals from /evolve
│
├── .claude/
│ ├── commands/ # Developer-facing workflow commands
│ │ ├── start-issue.md
│ │ ├── setup-issue-docs.md # Level 2 only
│ │ ├── plan-pr.md
│ │ ├── implement.md
│ │ ├── capture-learnings.md # Level 2 only
│ │ ├── close-issue.md
│ │ ├── record.md # Post-session retrospective
│ │ └── evolve.md # Process maturation proposals
│ ├── agents/ # Subagents for heavy context work
│ │ ├── sdd-generator.md # Generates Software Design Documents
│ │ ├── plan-generator.md # Generates implementation plans
│ │ └── test-validator.md # Adversarial test review
│ └── skills/ # Domain knowledge for agents
│ ├── linear-workflow/SKILL.md # Linear interaction patterns
│ └── [project-specific]/ # Tech stack, coding standards, etc.
│
└── [source code] # The actual codebase
├── src/ # Or whatever the project structure is
├── tests/
├── package.json # Or equivalent
└── ...
Document Categories
Living Documents (Updated by /capture-learnings)
These files reflect the current truth about the project. They are updated after each completed issue and should always be accurate.
| File | Purpose | Created By | Updated By |
|---|---|---|---|
current-architecture.md |
System architecture, components, data models, API endpoints | Intake or onboard | /capture-learnings merges target architecture |
current-features.md |
Feature inventory with issue numbers and dates | Intake or onboard | /capture-learnings adds completed features |
current-security-assessment.md |
Security posture, findings, threat model, compliance | Intake or onboard | /capture-learnings adds security updates |
current-test-strategy.md |
Test philosophy, coverage targets, invariants, threat models | Intake | /capture-learnings updates with test learnings |
Key principle: Living documents are the developer's primary reference. They should be readable without context about specific issues or PRs.
Active Documents (Per Issue/PR)
These files exist for the duration of a single issue or PR. They are the working context during implementation.
| File | Purpose | Created By | Archived By |
|---|---|---|---|
sdd-[TICKET]-[PR#].md |
Software Design Document — architecture, components, test design | /plan-pr (via SDD agent) |
/capture-learnings |
plan-[TICKET]-[PR#].md |
Implementation plan — subtasks with checkboxes, success criteria | /plan-pr (via planning agent) |
/capture-learnings |
pr-tracking-[TICKET].md |
PR breakdown table for multi-PR issues | /setup-issue-docs |
/capture-learnings |
target-features-[TICKET].md |
Desired feature state after this issue | /setup-issue-docs |
/capture-learnings |
target-architecture-[TICKET].md |
Proposed architecture changes | /setup-issue-docs |
/capture-learnings |
target-security-assessment-[TICKET].md |
Security implications of this issue | /setup-issue-docs |
/capture-learnings |
Key principle: Active documents are temporary. They provide focused context for the current work and are archived when the issue completes. This keeps the docs/ directory clean and the active set small.
Permanent Documents
These files are created once and never archived. They accumulate project knowledge permanently.
| File | Purpose | Created By |
|---|---|---|
adr/ADR-NNN-*.md |
Architecture Decision Records — major decisions with rationale | /capture-learnings |
guides/*.md |
Repeatable procedures — how to do specific things | /capture-learnings |
The 6-Document Active Set
At any point during implementation, the developer's mental model is limited to:
┌─────────────────────────────────────────────────────────┐
│ THE DEVELOPER'S WORLD DURING IMPLEMENTATION │
│ │
│ Living (background reference): │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ 1. current-architecture.md — how things work │ │
│ │ 2. current-features.md — what's built │ │
│ │ 3. current-security-assessment.md — security state │ │
│ │ 4. current-test-strategy.md — how we test │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ Active (current focus): │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ 5. sdd-[TICKET]-[PR#].md — design for this PR │ │
│ │ 6. plan-[TICKET]-[PR#].md — steps for this PR │ │
│ └─────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘
Everything else is consumed by commands and agents — the developer doesn't need to know about it.
Level 1 vs Level 2 Structure
Level 1 (Exploratory/Demo)
A simpler structure for prototypes and demos:
[project-name]/
├── CLAUDE.md
├── README.md
├── context/ # From intake
│ ├── requirements.md
│ ├── decisions.md
│ └── constraints.md
├── docs/
│ ├── development/
│ │ ├── sdd-[TICKET].md # One SDD per ticket (no PR# needed)
│ │ └── archive/
│ ├── planning/
│ │ ├── plan-[TICKET].md # One plan per ticket
│ │ ├── project-checklist.md # Simple ticket tracking
│ │ └── archive/
│ └── requirements/
│ └── prd-*.md # If PRD exists from PM project
├── .claude/
│ ├── commands/
│ │ ├── start-ticket.md
│ │ ├── plan-ticket.md
│ │ ├── implement.md
│ │ └── complete-ticket.md
│ ├── agents/
│ │ └── sdd-generator.md
│ └── skills/
│ └── [project-specific]/
└── [source code]
What's missing vs Level 2: No living documents, no target docs, no capture-learnings, no ADRs, no multi-PR tracking. These are added when the project graduates.
Context Files (From Intake)
Context files are created during intake and serve as the project's foundation. They inform the generation of living documents and command configurations.
| File | What It Captures |
|---|---|
context/requirements.md |
Purpose, users, success criteria, development approach |
context/decisions.md |
Key decisions with rationale (numbered, with status) |
context/constraints.md |
Technical constraints, team limits, timeline, infrastructure |
context/questions.md |
Open questions with "what we know / don't know / how to explore" |
SDD Structure
The Software Design Document is the most important active document. It feeds directly into implementation.
Typical SDD sections:
- Overview — What this PR implements, why, relationship to the issue
- Architecture — Component design, data models, API changes (with mermaid diagrams)
- Implementation approach — Key technical decisions, patterns to follow
- Test design — Specification-based test expectations:
- Invariants that must hold
- Expected behaviors to verify
- Failure modes to catch
- Edge cases to cover
- Dependencies — What this PR depends on, what depends on it
- Risks and mitigations — What could go wrong, how we handle it
Plan Structure
The implementation plan is the execution roadmap. /implement reads this file and works through subtasks sequentially.
Typical plan sections:
- Overview — Branch, issue reference, effort estimate
- Subtasks — Ordered list with checkboxes:
- [ ] Subtask 1: Description - Success criteria: ... - Files to create/modify: ... - [ ] Subtask 2: Description ... - Definition of done — What "complete" means for this PR
- Notes — Context the implementer needs
Key principle: Each subtask corresponds to one /implement call. Subtasks should be sized for a single focused implementation pass.
Git Configuration
The project should have its own git repository. Suggested .gitignore:
.DS_Store
*.swp
*.swo
.claude/settings.local.json
node_modules/
dist/
.env
.env.local
CLAUDE.md Sections
The CLAUDE.md for a software development project typically includes:
- Project identity — What this is, tech stack, architecture overview
- Development workflow — Command reference with the workflow sequence
- Coding standards — Style, patterns, anti-patterns specific to this project
- Context hierarchy — Which docs to read first (living docs → active docs → guides)
- Architecture patterns — Key patterns in the codebase (component structure, data flow, state management)
- Testing conventions — Framework, coverage targets, how tests relate to SDDs
- Git conventions — Branch naming, commit format, PR process
- MCP servers — What's required (Linear) and what's optional
- Cross-project references — Sibling projects, shared libraries, external dependencies
- Key constraints — Non-negotiables, anti-patterns to avoid