The blog
How to understand a codebase fast — and give your coding agents the context they need.
Guides
19
How to Read an Unfamiliar Codebase: A Step-by-Step Method
A repeatable, step-by-step method for reading code you did not write, from the first ten minutes to a working mental model you can explain to someone else.
14 min read
Reading Code Is a Skill: Why It Matters and How to Practice
Engineers spend far more time reading code than writing it, yet almost nobody practices reading on purpose. Here is what skilled readers do and how to train it.
11 min read
How to Find the Entry Point of Any Repository, in Any Stack
Every codebase starts somewhere the outside world touches it. This is a field guide to finding main functions, routes, CLI commands, workers and build entry points in any stack.
11 min read
How to Trace a Request Through a Web App, Route to Database
Following one HTTP request end to end is the fastest way to understand a web backend. Here is the path every request takes and how to trace each hop.
12 min read
Your First Open Source Contribution: Find Your Way, Land a PR
How to pick an open source project, find an issue you can actually finish, get oriented in an unfamiliar repo, and open a pull request maintainers are glad to merge.
11 min read
Learn by Reading Open Source Code: Repos and Techniques
Real codebases teach things tutorials cannot. How to choose open source repos worth reading, how to read them so the lessons stick, and a starter list by topic.
10 min read
Dependency Graphs Explained: How to Read the Shape of Code
A dependency graph is the fastest honest picture of how a codebase hangs together. Learn what it shows, how to generate one, and how to read the shapes that keep showing up.
11 min read
Call Graphs Explained: Static vs Dynamic, Limits and Uses
A call graph answers who calls what. Static and dynamic call graphs answer it differently, and both have blind spots. Here is how they work and when to trust them.
11 min read
How to Find and Fix Circular Dependencies in Your Codebase
Circular dependencies cause load-order bugs, slow builds and tangled designs. This guide covers detection tools per language, five refactoring patterns, and CI rules that keep cycles out.
12 min read
Architecture Decision Records: A Guide to ADRs People Use
Most ADR collections die after the fifth record. This guide covers what to record, a template that stays short, a review workflow, and how to connect decisions to code so people find them.
12 min read
How to Find Dead Code (and Remove It Safely) in Any Language
Static tools find candidates, runtime data confirms them, and a staged removal keeps you safe. Here is the toolkit per language and the process around it.
11 min read
How to Explain Code and Systems to Non-Engineers
Non-engineers do not need to understand the code. They need to make a decision. This guide shows how to explain systems in terms of that decision, with templates.
10 min read
How to Run a Codebase Walkthrough Your Team Will Remember
Most codebase walkthroughs are an hour of scrolling. A good one follows one real flow through a handful of stops and leaves behind an outline people can reuse.
12 min read
Shared Workspaces for Humans and AI Agents (2026 Guide)
Coding agents can now take a ticket to a pull request. The question is no longer which assistant to use, but where people and all their agents meet. A field guide to the category.
9 min read
How to Assign Tickets to Claude Code and Codex as Teammates
The step-by-step workflow for turning a coding agent on your laptop into a team member that takes tickets, publishes a plan and opens a PR — plus what belongs in the ticket.
7 min read
Human-in-the-Loop for AI Coding Agents Without the Drag
Review is where agent productivity goes to die, unless the controls are designed. Four structural controls, one review loop, and the anti-patterns that turn oversight into a bottleneck.
8 min read
The Complete Guide to Code Knowledge Graphs for AI Agents
A code knowledge graph turns a repository into nodes and edges an AI agent can query. This guide covers how graphs are built, kept fresh, queried over MCP, and evaluated.
26 min read
AI Codebase Context: A Practical Guide for Better Coding Agents
A coding agent is only as reliable as the context it receives. This practical guide explains what useful repository context contains and how to deliver it efficiently.
6 min read
How AI Coding Agents Actually Understand a Codebase
Under the hood, most agents explore a repository the same way a new hire with no map would: open a file, read it, open the next. That’s where the tokens go.
6 min read
Stack guides
9How to Understand a Next.js Codebase: App Router to Middleware
A field guide to reading a Next.js App Router project: which files matter, where the server/client line sits, how requests flow, and what to check first.
13 min read
How to Understand a React Codebase: Trees, State and Hidden Logic
A practical method for reading a React app: entry point, router, provider stack, state by category, data fetching, and the places logic hides in effects and hooks.
11 min read
How to Understand a Django Project: Settings to Signals
A step-by-step route through an unfamiliar Django codebase, with the manage.py commands that reveal its structure and the places behavior hides.
10 min read
How to Understand a Rails App: Routes, Callbacks and Concerns
Rails runs on convention, which is great until you need to find where something happens. Here is the reading order and the commands that make a Rails app legible.
11 min read
How to Understand a Go Codebase: cmd, internal and Wiring in main
Go codebases are explicit by design, which makes them readable if you follow the right order: module, binaries, main, packages, interfaces and concurrency.
12 min read
How to Understand a Rust Codebase: Crates, Traits and Features
A practical reading order for unfamiliar Rust projects, from Cargo.toml and the module tree to trait implementations, feature flags, build scripts and unsafe blocks.
12 min read
How to Navigate a Python Monorepo: Packages, Imports, Boundaries
Python has no single monorepo standard, so every repo is assembled differently. Here is how to work out the packages, the import paths, the tooling and the rules.
12 min read
How to Navigate a TypeScript Monorepo: Workspaces to Build Graph
A practical guide to reading a TypeScript monorepo: package manager workspaces, internal packages, tsconfig project references, the task graph and boundary rules.
11 min read
How to Understand a Spring Boot Project: Beans to Profiles
Spring Boot hides wiring behind annotations and auto-configuration. This guide shows where to look and which Actuator endpoints and flags reveal what is really running.
11 min read
AI coding agents
11Claude Code Codebase Context: CLAUDE.md, MCP, and Workflow
Give Claude Code structural context up front with a curated CLAUDE.md, MCP tools for definitions and callers, and a five-step session workflow.
14 min read
Codex CLI on Large Repositories: AGENTS.md, Scoping, and MCP
How to keep Codex CLI fast and accurate on big monorepos: nested AGENTS.md files, scoped prompts, structural context over MCP, and reviewable runs.
13 min read
Gemini CLI Codebase Context: Long Context vs Retrieval
A big context window is most useful once something else has chosen what goes in it. Here is how to combine GEMINI.md, retrieval, and long context.
11 min read
Choosing an AI Coding Agent for Large Repos: Criteria and Tests
Public benchmarks do not reflect your monorepo. This is a vendor-neutral way to compare coding agents on your own code and tasks.
10 min read
Writing AGENTS.md and CLAUDE.md Files That Agents Follow
Agent instruction files are the cheapest lever you have over coding agents. What to put in them, how to structure them, and what to leave out.
12 min read
Prompting Coding Agents for Refactors Without Breaking Things
A refactor is defined by what it preserves. How to frame refactoring prompts so agents change structure, not behavior.
12 min read
How to Stop AI Coding Agents From Hallucinating APIs
Agents invent functions when they write from pattern memory instead of your code. Grounding with real symbols, types, and tests fixes most of it.
11 min read
RAG for Code: Where Chunk-and-Embed Retrieval Breaks
Chunk-and-embed retrieval was built for documents. On code it finds what looks related, not what is related. Here is what to add.
10 min read
AI Code Explanation Tools: What Good Looks Like and How to Test
The gap between a useful AI code explanation and a fluent restatement is grounding and structure. How to tell them apart on your own code.
10 min read
Local-First Code Indexing: Privacy, Threats, and Vendor Questions
Where your code is parsed and indexed decides who can see it. A threat model for code intelligence tools and the vendor questions that matter.
9 min read
Using an MCP Server to Give AI Agents Codebase Context
MCP gives coding agents a standard way to ask external tools for context. A code graph server turns vague repository exploration into precise structural queries.
6 min read
Playbooks
8How to Understand a Large Codebase Fast (Days, Not Months)
A practical five-day plan for getting a working mental model of a very large repository, by reading structure and history first and source code last.
13 min read
Your First Week on a New Codebase: A Day-by-Day Checklist
A practical, day-by-day checklist for a new engineer's first week, from getting the build green to shipping a first small change and writing down what you learned.
13 min read
How to Review a Pull Request in Code You Don't Know
A practical method for reviewing changes in a part of the codebase you have never worked in, from building context to writing comments that help.
11 min read
Engineering Handoff Checklist: When a Developer Leaves the Team
Two to four weeks is enough for a solid handoff if you start from data, not memory. This checklist covers ownership, systems, access, open work and the unwritten context.
10 min read
Debugging an Unfamiliar Service During an Incident
You are paged for a service you have never touched. This is a calm, ordered method for orienting fast, mitigating safely and finding the cause in unfamiliar code.
12 min read
Reviewing AI Agent Pull Requests: The Team Playbook
AI agents open pull requests faster than humans can read them. This playbook covers blast radius checks, review checklists, diff size limits, approvals, review roles and the metrics that tell you whether it works.
29 min read
Running an Engineering Team With AI Agents: A Playbook
A practical playbook for agent roles, tickets agents can finish, permissions, branches, handoffs, channels and cost control, with a 30-day rollout plan.
25 min read
Five Ways to Cut Your AI Coding Agent’s Token Bill
Token bills balloon because agents re-read the same files to answer overlapping questions. Here are five concrete levers, in rough order of impact.
5 min read
Deep dives
15How to Understand Legacy Code: Archaeology, Seams and Tests
Legacy code is code you need to change but do not yet understand. Git archaeology, characterization tests and seams turn it from a risk into something you can work with.
12 min read
How to Understand a Microservices Architecture You Inherited
Microservices move complexity from code into the spaces between services. Here is how to map those spaces: inventory, contracts, messaging, data ownership and traces.
11 min read
Architecture Diagrams That Stay Accurate: Generated vs Curated
Hand-drawn architecture diagrams go stale within months. Here is why it happens and a practical system for keeping diagrams honest: curate intent, generate structure, and check one against the other.
13 min read
C4 Model vs Generated Architecture Maps: When to Use Each
The C4 model gives you a shared vocabulary for intent. Generated maps tell you what the code actually does. This post explains when each wins and how to use them together.
11 min read
Code Hotspots: Using Churn Analysis to Find What to Fix First
Not all messy code matters. Hotspot analysis combines how often a file changes with how complex or central it is, so you spend refactoring time where it pays off.
12 min read
Module Boundaries and Coupling: How to Measure and Enforce Them
Boundaries that live only in a wiki erode. This post shows how to measure coupling with real numbers and how to enforce module boundaries with tools that fail the build.
12 min read
Documentation That Stays Current: Habits and Tooling That Work
Docs go stale because nothing forces them to change when code changes. Here is a system that does: docs near code, generated references, executable examples and review habits.
11 min read
Tree-sitter Explained: Parsing, Queries and How Code Tools Use It
Tree-sitter powers syntax highlighting, code navigation and code graphs across editors and tools. Learn how it parses, how its query language works, and where its limits are.
14 min read
How to Map Technical Debt With Hotspots and Dependency Data
A debt list built from opinions never gets funded. A map built from churn, complexity and dependencies shows where debt costs you, and what to fix first.
11 min read
Safe Refactoring in Large Codebases: Patterns That Work
Big refactors fail when they are big. These patterns turn a risky rewrite into a sequence of small, reversible, verified steps that ship continuously.
11 min read
Atlassian's Agentic Multiplayer Protocol for Small Teams
Atlassian just said agents should work like employees, with assigned identity, authority and scope. The idea is right. Here is what it means if you are eight people and not on Jira.
7 min read
AI Project Management for Software Teams: What Changes
There is a difference between an AI assistant inside your PM tool and agents that actually take tickets. The second changes how you plan, what a board shows and how you measure delivery.
8 min read
Codebase Visualization: How to Map a Large Repository
A useful codebase visualization is more than a directory tree. It shows the relationships that explain ownership, execution, risk, and change impact.
6 min read
Software Impact Analysis Before a Large Refactor
Refactors fail at the edges: an overlooked caller, serialized field, plugin, or test fixture. Impact analysis makes those edges visible before code changes.
5 min read
Code Knowledge Graph vs. Embeddings: Which Grounds an Agent Better?
Embeddings retrieve by resemblance; a graph retrieves by relationship. For questions like “what breaks if I change this?”, only one of them is answering the real question.
5 min read
Teams & onboarding
4How to Ask Better Questions About Code (to People and AI)
The quality of an answer about code depends mostly on the question. A simple structure for asking teammates and AI tools questions that get specific, checkable answers.
11 min read
Knowledge Silos and Bus Factor: How to Measure and Reduce Them
Bus factor is measurable from data you already have in git. This guide shows the commands, how to read the results, and a practical plan to spread knowledge.
12 min read
How to Measure Developer Onboarding Without Fooling Yourself
Time to first PR is easy to game and easy to misread. Here is a small set of onboarding metrics, how to collect them, and how to use them to fix the real problems.
10 min read
How to Onboard Developers to a Large Codebase Faster
The fastest onboarding does not explain every subsystem. It gives a new developer a reliable map, one end-to-end workflow, and a safe first change.
6 min read