Brownfield: suggested documentation layout

Maintain ARCHITECTURE.md and for larger modules a DESIGN.md
Walk the source code tree and get all filenames
- Put them in a to-do list
- Loop, asking for detailed write ups of all files, including last change timestamp for any file that has changed since the last documentating event
Create specs/FILENAME.md
Draft IMPLEMENTATION_PLAN.md
Human review
Implement the top item + tests

Narration

Listen or continue with the transcript

Auto-play audio on each slide

Transcript

When documenting a large codebase, having a consistent structure helps Claude Code navigate and understand your system more efficiently.

Here's a suggested documentation layout that works well for brownfield projects.

Start with an ARCHITECTURE.md file at the root. This is your high-level overview - describe the major components, how they interact, key design decisions, and any important architectural patterns. Think of this as the map that helps Claude understand how your major subsystems fit together.

Next, create a specs directory for detailed component specifications. Each major subsystem should have its own document here. For example, you might have specs for your API layer, your data processing pipeline, and your database schema. These go deeper than the architecture doc, describing interfaces, data structures, and behavior.

Finally, consider an IMPLEMENTATION_PLAN.md for any ongoing work. This helps Claude understand what's in progress, what's planned, and what constraints or conventions to follow. It's especially useful when you're actively refactoring or adding features.

This structure gives Claude clear entry points: start broad with architecture, drill down into specs when needed, and check the implementation plan for context about current work. It's much more effective than scattering documentation comments throughout thousands of lines of code.