In Session 4 you learned to review code for bugs and anti-patterns at the file level. This session scales those analysis skills to entire systems — using Claude to explore unfamiliar codebases, review architecture for problems and tradeoffs, and generate documentation you can actually trust.
Navigating Large and Unfamiliar Codebases
What it is: One of Claude’s biggest strengths is helping you get oriented in code you did not write. Instead of spending hours reading files one at a time, you give Claude an entry point and ask it to trace through the system — mapping dependencies, identifying patterns, and building you a mental model in minutes. The key is starting broad (“give me a 5-minute overview”) and then narrowing to the area you need to change (“trace the login flow from the route handler through every file it touches”). For large monorepos, use subagents to explore multiple areas in parallel so you are not waiting for sequential investigation.
Demo prompt:
I just joined this project. Give me a 5-minute overview:
1. What does this project do?
2. What's the tech stack?
3. How is the code organized (directory structure and key modules)?
4. What are the main entry points?
5. How do I build and run it?Try it now: Open Claude in a project you are less familiar with — a teammate’s service, an open-source dependency, or a part of your monorepo you rarely touch. Ask for the 5-minute overview, then follow up by asking Claude to trace a specific request path from entry point to database. Note how quickly you build a mental model compared to reading the code manually.
Go deeper: Subagents — use parallel investigation threads to explore multiple modules simultaneously instead of one at a time.
Architecture Review and Documentation Generation
What it is: Claude can analyze a system’s architecture and produce structured analysis — identifying coupling issues, inconsistent error handling, missing resilience patterns, and misplaced business logic. The most useful output format is an Architecture Decision Record (ADR), which captures the context, decision, alternatives, and consequences in a format your team can review and act on. The same exploration capabilities make Claude effective at generating documentation: point it at source files and existing tests, and it produces API docs, module overviews, or onboarding guides. The critical step is validation — AI-generated documentation that looks plausible but contains inaccuracies is worse than no documentation, so always verify against the actual code.
Demo prompt:
Analyze this system using subagents:
- Subagent 1: Map all external API calls and third-party dependencies
- Subagent 2: Analyze the database schema, indexes, and query patterns
- Subagent 3: Map service boundaries and inter-service communication
- Subagent 4: Review error handling, retry logic, and resilience patterns
Produce a system overview with a focus on failure modes. Format the
top recommendation as an ADR with Status, Context, Decision,
Consequences, and Alternatives Considered.Try it now: Pick a service or module in your codebase that has grown organically — something with known rough edges. Ask Claude to analyze its architecture using the subagent pattern above. Review the ADR it produces: does it identify real problems? Does it miss anything you know about? This calibration between what Claude finds and what you already know is how you learn to trust (and verify) its analysis.
Go deeper: Plan Mode — use plan mode before large architecture tasks to get Claude’s proposed approach before it starts working.
Working with Existing Code Patterns
What it is: When you need to add or modify code in an established codebase, the biggest risk is not bugs — it is writing code that does not match existing patterns. Claude can read your codebase’s conventions (naming, error handling, dependency injection, test structure) and replicate them, but only if you explicitly tell it to look first. The pattern is: read existing examples, identify the conventions, then apply those conventions to the new code. This is the “explore” phase of the Explore-Plan-Code-Commit workflow from Session 2, and skipping it is the single most common reason Claude generates code that does not fit. When the existing patterns need improvement rather than replication, apply a Refactoring workflow: write characterization tests first (Session 3), then restructure with confidence.
Demo prompt:
I need to create a new ProductService. Before writing any code:
1. Read @src/services/UserService.java and @src/services/OrderService.java
2. Identify the common patterns: constructor injection, error handling,
return types, logging, transaction management
3. List the conventions I should follow
Then create ProductService following those exact patterns.Try it now: Find two or three similar files in your project (services, controllers, or test files). Ask Claude to read them and list the shared conventions. Then ask it to generate a new file of the same type. Compare the generated code against the originals — does it follow the patterns, or did it invent its own?
Go deeper: CLAUDE.md Configuration — encode your team’s conventions in CLAUDE.md so Claude follows them automatically in every session.
Key Takeaways
- Start broad, then narrow. A 5-minute overview followed by targeted tracing builds a mental model faster than reading files sequentially.
- Use subagents for parallel exploration. Investigating three modules simultaneously saves minutes of serial waiting on every investigation.
- Architecture analysis is most useful when structured as an ADR — it forces Claude to articulate context, alternatives, and consequences rather than just listing problems.
- AI-generated documentation must be validated against source code. Plausible-sounding docs with inaccuracies are worse than no docs.
- Always explore existing patterns before asking Claude to write new code. The explore phase takes two minutes and prevents twenty minutes of rework.
- For non-trivial projects, connect EPCC, TDD, and plan mode into a Structured Project Planning workflow with review checkpoints at every phase — context, explore, plan, build (TDD), persist, verify.
Practice
Take on larger challenges with the Intermediate Scenarios and Advanced Scenarios — architecture review, multi-file refactoring, and system-level analysis exercises.