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.