Chapter 3 - Codebase Exploration
Navigate unfamiliar codebases efficiently using instruction files, skills, and Model Context Protocol (MCP) to extract architecture insights without manual searching.
- Reading time: 20 minutes
- Practical time: 30-40 minutes
Reading
Briefs
CLAUDE.md and Copilot Instructions
Instruction files provide persistent context to AI coding agents. They establish project conventions, define architectural patterns, and supply domain knowledge so you don't repeat the same setup in every session.
Use instruction files to:
- Define tech stack and project structure
- Specify coding conventions and patterns
- Document build commands and workflows
- Provide business domain context
Tool-specific guides:
Official resources:
Skills
Skills extend AI coding agents with reusable, specialized capabilities triggered automatically by context. Think of them as custom tools the agent knows when to use.
A skill typically:
- Triggers automatically based on detected context
- Executes multi-step workflows
- Returns structured output
Examples: onboarding new developers, generating architecture diagrams, running project-specific tests.
Tool-specific guides:
Official resources:
Model Context Protocol (MCP)
MCP connects AI agents to external data sources and tools through a standardized protocol. Unlike skills (which are instruction-based workflows), MCP provides real-time access to live systems.
Skills vs MCP:
- Skills: Pre-defined workflows executed by the agent using existing tools
- MCP: External integrations that add new capabilities (databases, APIs, file systems)
Use MCP when you need to query external systems the agent can't otherwise access. Use skills when you want to automate multi-step processes with existing tools.
Tool-specific guides:
Assets
Configuration files and onboarding skill:
- Download: 03-codebase-exploration.tar.gz
⚠️ Important: Extract and overwrite the configuration files for your chosen tool (Claude Code or Copilot CLI). These assets contain tool-specific settings that should replace any existing configuration in your project.
Practical
Task 1: Extract Architecture Information
Start a CLI session and ask the agent to answer these questions about the codebase:
- What is the tech stack of the project and what versions are used?
- What are the relevant endpoints used in the project?
- How is the API documented?
- How can I run the BE application?
- How can I run the UI application?
- What are some architectural patterns used in the application BE?
- What are some architectural patterns used in the application FE?
- What database is used?
- Are there any relevant third-party libraries used in the application?
- How is the UI styling done?
What to observe:
- How quickly the agent locates configuration files
- Whether it identifies package.json, pom.xml, or equivalent dependency files
- If it finds README documentation or infers from code structure
Task 2: Configure Project-Specific Instructions
Extract and copy the configuration files from the Assets section into your project based on the tool you use.
Restart your CLI session (CTRL+C) to load the new configuration.
Ask the agent questions about the project setup and observe how responses change with the instruction files present.
Task 3: Use the Onboarding Skill
Start the application using the information from Task 1.
Run the onboarding skill:
/onboard-appWhat to observe:
- How the skill walks you through the application structure
- What information it surfaces automatically vs. what you had to ask manually
- Time saved compared to manual exploration
- Imagine if it would help inside a larger app for new developers