Track 14 · Advanced

14.1

Building complex codebases

Make an AI agent reliable on a large, real codebase

16 lessons 2026-08-08 AI-generated

1Overview

A discipline (not a tool) for making an AI coding agent reliable on a large, real codebase — tool-agnostic, anchored on Cole Medin's open-source workflow.

A discipline, not a tool: how to get an AI coding assistant to work reliably on a big, real codebase instead of "vibe coding" one-offs. The core idea — popularised by Cole Medin — is a second "AI layer" checked into source control next to your code (a lean CLAUDE.md of rules, reusable commands, and later skills, subagents and MCP), driven by a tight Plan → Implement → Validate loop. → Unlike the AI coding assistants chapter (which tool to use), this chapter is about the workflow that makes any of them dependable at scale. Tool-agnostic, but Claude Code is the running example. → Next rung: Self-host on a private cloud — ship it yourself, safely, once it works.

1.1Before you start

Install Claude Code— The running example throughout. One install command on macOS, Windows (WSL) or Linux, then you type prompts into your terminal inside the project folder — that is where every lesson below starts.A repo you can push to— The AI layer is checked into git, so you need a project under version control. If you have never made one, the Gitea and GitHub lessons in this chapter start from an empty account.

1.2After this chapter you can

→Build a version-controlled "AI layer" (CLAUDE.md + reusable commands) for a real project

→Run any task through the Plan → Implement → Validate loop

→Scale up with skills, subagents and MCP — without overengineering

→Turn each agent mistake into a permanent fix to your system

1.3When to reach for it

When "vibe coding" stops working — the project is too big for the agent to hold in its head and new changes start breaking old things.

1.4Key parts

A version-controlled "AI layer" (a lean CLAUDE.md + reusable commands), and the Plan → Implement → Validate loop.

2Lessons 16

2.1 Make an AI agent work on large codebases

A CLAUDE.md file stores project rules that the AI layer reads to guide its output.

Add a version‑controlled AI layer so the agent can reliably work on a large repository

Try

In the building‑complex‑codebases UI, open the existing repo large-app, type the request “Add a logging helper that follows the project’s conventions and update the related tests”, and submit it. Then create a file named CLAUDE.md at the repo root with the rule “All logs must use logger.info with tag [APP]”, commit the change, and repeat the exact same request.

Paste the whole text into the chat input box of the building‑complex‑codebases tool. Watch how the first response guesses the logging style, while after adding CLAUDE.md the second response follows the rule exactly.

Create a CLAUDE.md file in the repository root and write project rules there
Add the file to Git with git add CLAUDE.md
Commit the change using git commit -m "Add AI layer"

You'll see Subsequent one‑line requests produce code that follows the defined project rules
Takeaway A checked‑in AI layer supplies consistent context for reliable agent output
Check How does committing a CLAUDE.md file change the way the AI agent generates code?
Cost The AI layer is upfront effort — an hour or two on a real repo — that pays back on every task afterwards. It's a habit, not a purchase.

2.2 Create and explore your first repository

A repository is a shared folder plus its full edit history, and Gitea provides a self‑hosted Git forge where that repo lives.

Create a repository, push an initial file, and explore the dashboard UI

Try

Click + New Repository, name it lab-notebook, tick 'Initialize Repository', then edit README.md directly in the browser and commit the change.

No git command line needed for this first step — Gitea's web editor commits for you.

A Gitea repository page (gitea/tea) showing the Code, Issues, Pull Requests and Actions tabs, the file list, commit history and MIT licence — **This is your project's home page** — and the whole forge in one view: files and commit history in the middle, and tabs for Issues, Pull Requests and Actions across the top. Self-hosted, so it all lives on your server. Credit: gitea.com ↗

Click + New Repository, fill in name and description, choose visibility and create it
Navigate the dashboard to view the file list, rendered README and branch selector at the top
Add or edit a file via the web UI (or clone, modify and push) and watch the new commit appear in history

You'll see A file list with the README displayed below and a fresh commit shown in the history panel
Takeaway Gitea hosts a Git repo on your own server while preserving the familiar files‑plus‑history model
Check What three pieces of information does the Gitea dashboard show after you create a repository?
Cost Gitea itself is free and open-source (MIT license) — no seat limits, no repo limits, run as many instances as you like.

2.3 Host a repository on GitHub

GitHub is a hosted platform built on Git that adds a web UI, pull requests, issues and AI integration on top of plain version control.

Create an account, push a repo to GitHub and observe the additional collaboration features it provides

Try

Create a free account at github.com, click New repository, name it (e.g. lab-notebook), and initialize it with a README. Then either clone it locally (git clone <url>) or, if you already have a local repo, add GitHub as a remote: git remote add origin <url> && git push -u origin main.

No git experience? GitHub Desktop or VS Code's Source Control panel do the same steps with buttons instead of commands.

The scverse/scanpy GitHub repository page showing the file browser, rendered README, and the Code / Issues / Pull requests / Actions tab bar — **A repo page is your project's front door** — file tree, README, commit history, and every collaboration tab live here (this is scanpy, a real single-cell analysis project). Credit: github.com ↗

Create a new repository using New repository or push an existing local one as the remote
Open the repo page to see the rendered README, file browser, commit history and navigation tabs
Add a collaborator via Settings → Collaborators

You'll see A live GitHub page showing the README, file tree, commit list and tabs for Code, Issues, Pull requests and Actions
Takeaway GitHub layers collaboration tools over Git, enabling AI agents to interact directly with hosted code
Check Which UI elements appear on a newly created GitHub repository that are not present in a bare local Git repo?
Cost Free tier: unlimited public and private repos, unlimited collaborators, no credit card needed. Verified students get GitHub Pro free via the Student Developer Pack (education.github.com/pack).

2.4 Create a lean CLAUDE.md for your project

A hierarchical set of CLAUDE.md files—global, repository‑specific and local—defines where the agent looks for rules.

Do this first Make an AI agent work on large codebases

Provide concise build, test and lint instructions plus repository rules for the agent at session start

Try

In the repository root, create a new file named CLAUDE.md and paste these lines:
```
# Build Commands
./gradlew build
./gradlew test
./gradlew lint

# Directory Map
src/        – source code
tests/      – unit tests
docs/       – documentation
configs/    – configuration files

# Hard Rules
- Never modify files in `vendor/`.
- All new modules must include a corresponding test file.
- Lint must pass before any commit.
```
Save the file.

Open the File Explorer in the building-complex-codebases UI, click + New File, name it CLAUDE.md, paste the content and hit Save. Verify the file is under 150 lines to keep the prompt lean.

Add a CLAUDE.md file to the repository root containing essential commands, a brief directory map and hard rules
Edit the file so each line is high‑signal and keep the total under roughly 150 lines
Organise rule locations using the hierarchy: personal defaults in ~/.claude/CLAUDE.md, repo‑specific rules in ./CLAUDE.md and optional notes in a git‑ignored local file

You'll see The agent automatically follows the defined conventions, applying correct folders, commands and guardrails without extra prompts
Takeaway One well‑crafted CLAUDE.md file gives every future session immediate awareness of your codebase
Check What three locations are used to store hierarchical CLAUDE.md rule files?
Cost CLAUDE.md loads every session, so every extra line is paid for on every message. Trimming to essentials keeps the agent both cheaper and more obedient.

2.5 Propose, review and merge changes

A branch is an isolated copy of the project, and a pull request (PR) proposes merging that branch back into main after review.

Do this first Create and explore your first repository

Create a pull request, examine its diff and merge it into the main branch

Try

Create a branch called add-protocol-notes, edit a file on it, then open a pull request against main and leave a review comment on one line.

PRs work the same whether the branch came from a person or an AI coding agent — review the diff either way.

A merged Gitea pull request on the Files Changed tab, showing the file tree and a green line diff — **Every change is reviewed before it lands** — a merged pull request with its file tree and green/red diff, on a self-hosted Gitea (this is the very forge that hosts this course). Credit: 32dots Gitea

Create a new branch from the repository to isolate your edits
Open a pull request so Gitea displays a line‑by‑line diff between the branch and main
Review the changes, add inline comments if needed and click the merge button once satisfied

You'll see A diff view with green additions, red deletions and an enabled merge button after checks pass
Takeaway Pull requests act as a safety net, ensuring no AI‑generated code reaches main without review
Check What three actions complete the PR workflow in Gitea from branch creation to merging?
Cost Included free with self-hosted Gitea — unlimited PRs and reviewers, no per-seat charge.

2.6 Open, review, and merge a pull request

A pull request (PR) on GitHub lets you propose changes from a branch, view a diff, comment and approve before merging into main.

Do this first Host a repository on GitHub

Open a pull request, review its file changes and merge it into the main branch

Try

Create a new branch (git checkout -b fix-typo), edit one line — e.g. fix a typo in the README — commit and push it (git push -u origin fix-typo), then click Compare & pull request on GitHub.

Or skip the terminal entirely: click the pencil icon on any file in the GitHub web UI, and it creates the branch and PR for you.

A merged GitHub pull request (scanpy #4223) on the Files changed tab showing a green-and-red line diff and the file tree — **Files changed is where review happens** — deleted lines in red, added lines in green, and every changed file listed on the left. Credit: github.com ↗

Click Open pull request against main and write a concise description of the change
Select the Files changed tab to view red deletions and green additions, adding inline comments as needed
Press the green Merge pull request button after all feedback is addressed

You'll see A PR page showing the Files changed tab with coloured diffs and a green Merge pull request button once approved
Takeaway Pull requests provide a repeatable review loop that underpins reliable AI‑assisted modifications
Check Which three UI elements are involved when reviewing and merging a GitHub pull request?
Cost Free on every tier — pull requests, reviews, and diffs cost nothing regardless of plan.

2.7 Create reusable, version‑controlled commands

A /.claude/commands/ markdown file defines a slash command that can be invoked to load preset context.

Do this first Create a lean CLAUDE.md for your project

Create a shared, version‑controlled command that can be invoked from any session instead of retyping prompts

Try

Create a markdown file at .claude/commands/prime.md with a short description and the steps to load the current ticket, the repository file tree, and recent git history. Save the file, then invoke the new command by typing /prime in a chat session.

Paste this into the editor screen of the building‑complex‑codebases tool and click Save; ensure the file path is exactly .claude/commands/prime.md so it’s tracked by git. After saving, test the command by entering /prime in the chat.

Save the markdown definition inside .claude/commands/ in your project
Commit the new file to git so it is tracked and shared across the team
Invoke the command with /prime to load context in a fresh session

You'll see A single‑word slash command loads the ticket, file tree and recent git history for every participant
Takeaway Any repeated prompt can become a version‑controlled command that streamlines the whole team's workflow
Check What three steps turn a frequent prompt into a reusable /prime command?
Cost Writing a command is a few minutes once; it then saves that setup on every future task. The .claude/ folder is the asset, not any single session.

2.8 File and link an issue

An issue tracks a unit of work—bug, task or question—and lives alongside the code with its own comment thread, labels and assignee.

Do this first Propose, review and merge changes

Create an issue, label it, and link it to a commit so it closes automatically when merged

Try

Open a new issue titled 'Sample IDs inconsistent in batch import', add a label, assign it to yourself, and reference it in a commit message as Fixes #<issue-number>.

Referencing the issue number in a commit or PR auto-closes it when merged.

A Gitea issues list showing open issues with the Label / Milestone / Assignee / Sort filter bar — **A backlog that lives with your code** — open issues plus a filter bar for labels, milestones and assignees, on a self-hosted Gitea. Credit: 32dots Gitea

Click New Issue, write a description using Markdown and add any checklists or attachments
Select appropriate labels and choose an assignee from the dropdown menu
Reference the issue number (e.g. #12) in a commit message or PR description to close it on merge

You'll see The new issue appears with its label chip and assignee avatar, then shows a closed state after the linked commit merges
Takeaway Issues attach work items directly to the codebase and can be auto‑closed by linked commits
Check How does referencing an issue number in a commit message affect the issue’s status?
Cost Free, unlimited issues per repo — no separate project-management tool needed.

2.9 File a scoped issue and track it on a project board

Issues on GitHub capture bugs, tasks or questions, while Projects provide a kanban board to organise those issues into columns such as To do, In progress and Done.

Do this first Host a repository on GitHub

Create a scoped issue, label it for filtering and place its card on a project board

Try

Open your repo's Issues tab, click New issue, and write one concrete task, e.g. 'Add a unit test for normalize_counts()'. Add a label. Then open the Projects tab, create a board, and add the issue to it.

Keep the issue to one clear, scoped task, not a vague wishlist — vague issues get vague pull requests, from humans and AI alike.

The scanpy GitHub Issues list showing open issues with titles, labels, and metadata — **Every issue is a scoped, assignable unit of work** — titles, labels, and filters keep a busy backlog searchable (scanpy has 478 open). Credit: github.com ↗

Enter a clear title and description in New issue to define the work and acceptance criteria
Add relevant labels (bug, enhancement, etc.) using the Labels selector
Open Projects, add the issue as a card and drag it between columns as work progresses

You'll see A numbered issue appears in the Issues list and a corresponding card shows up on the selected Project board
Takeaway Well‑scoped issues drive both tracking and visual workflow management for human and AI contributors
Check What three actions connect an issue to a project board and make it visible as a moving card?
Cost Free on every tier — unlimited Issues and Projects. GitHub's own AI features on Issues (like assigning one to Copilot) are billed separately, under Copilot.

2.10 Run a Plan‑Implement‑Validate loop on real code

The Plan‑Implement‑Validate loop structures work into three phases where the agent plans, writes code and validates checks before finishing.

Do this first Create reusable, version‑controlled commands

Execute the Plan‑Implement‑Validate loop so the agent only finishes when all checks pass

Try

In the **Plan** screen, type a Product Requirements Prompt that adds a function `calculate_stats(data: List[float]) -> Dict[str, float]` to *stats.py*, updates *requirements.txt* if needed, creates unit tests in *test_stats.py* (checking mean, median, stddev), and specifies lint and type‑check must pass. Then click **Implement**, paste the same PRP into the fresh implementation window and generate the code. Finally click **Validate** to run `/validate` and view the results.

Paste the full PRP in the Plan dialog, then use the Implement button to start a new clean session and finally hit Validate; watch for any failing test or lint error—those indicate the loop isn’t complete yet.

Prompt the agent to produce a Product Requirements Prompt (PRP) that lists steps, files and required checks
Start a fresh session and run the implement phase following the PRP without prior context
Run lint, type‑check and tests then use /validate or /review to confirm all checks succeed

You'll see The agent creates a plan, writes code from a clean slate and reports completion only after passing lint, type‑check and tests
Takeaway Running PIV forces the agent to prove its work and prevents recurring bugs
Check Which three stages must be completed in order for the agent to report successful task completion?
Cost Planning and validating add minutes up front, but they're far cheaper than debugging a confident wrong implementation later — and the loop gets faster as your rules accumulate.

2.11 Run CI automatically on each push

Gitea Actions is a built‑in CI/CD system that runs YAML workflow files placed in .gitea/workflows/ on every push, compatible with GitHub Actions syntax.

Do this first File and link an issue

Wire up an automatic workflow that triggers on each push and observe its execution

Try

Add .gitea/workflows/test.yml with a job that checks out the repo and runs your test command, then push — watch it run under the repo's Actions tab.

An existing GitHub Actions workflow will usually run on Gitea Actions with no changes.

A Gitea Actions tab listing workflow runs with green success ticks, workflow names (ci.yml, deploy-prod.yml) and commit shas — **CI that never leaves your server** — real build-and-deploy workflow runs on a self-hosted Gitea runner, green ticks and all. Credit: 32dots Gitea

Enable a runner by clicking Enable a runner to register a Gitea Runner with your instance
Create a YAML workflow file in .gitea/workflows/ defining the on: push trigger and steps such as checkout, install and test
Push the commit and open the Actions tab to watch the run’s live status and logs

You'll see A green check mark appears on the latest commit and a step‑by‑step log is shown under the Actions tab
Takeaway Gitea Actions turns every push into an automatic test run without relying on external CI services
Check What three actions are required to set up Gitea Actions that run on each push?
Cost Free — you supply the compute (your own runner), so there's no per-minute CI bill.

2.12 Run a CI workflow on every push

GitHub Actions runs YAML workflow files in .github/workflows/ on events like pushes, providing a fresh VM to execute steps such as tests, linting or AI‑driven checks.

Do this first Open, review, and merge a pull request

Run a CI workflow on every push and watch its result in the Actions tab

Try

Create .github/workflows/test.yml with:

on: push
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: echo "Hello from Actions"

Commit and push it, then open the Actions tab.

Indentation matters in YAML — copy it exactly, or edit the file directly in the GitHub web UI to avoid whitespace mistakes.

The scanpy GitHub Actions tab showing a list of workflow runs with green and red status icons — **Every run is logged with a status** — a green check for success, a red X for failure, full console output one click away. Credit: github.com ↗

Add a workflow file to .github/workflows/; GitHub automatically picks it up
Open the Actions tab after pushing to see a new run appear within seconds
Click the run, expand steps and read the log output to verify execution

You'll see A workflow run appears in the Actions tab, turns green when finished and shows “Hello from Actions” in the expanded log
Takeaway GitHub Actions makes the repository an automation platform that can also execute AI steps within pipelines
Check Which three observations confirm a successful GitHub Actions run after pushing a workflow file?
Cost Free tier: 2,000 Actions minutes/month (public repos run unlimited). Team adds 3,000 shared minutes; heavier CI means paying per-minute overages or upgrading.

2.13 Add skills, subagents and MCP only when required

A SKILL.md file describes a skill that can be referenced by the agent, while subagents and an MCP server extend functionality on demand.

Do this first Run a Plan‑Implement‑Validate loop on real code

Add heavier AI layers—skills, subagents and MCP—only when a concrete need is demonstrated

Try

Create a file SKILL.md in the repository describing a ‘Data Cleaning’ procedure that removes rows with missing values from data.csv, then ask the agent to use this skill on data.csv.

Paste the prompt into the Agent Console and hit Run; verify that the agent loads the new skill only for this task and does not add extra context otherwise.

Create a SKILL.md file describing the procedure and required steps
Reference the skill in the agent configuration so it loads only when relevant
Define a subagent with its own isolated context for parallel work
Launch the subagent from the main thread when an independent task is identified
Configure an MCP server to connect to external systems such as GitHub or Jira
Invoke the MCP endpoint from the agent after confirming real‑world data is needed

You'll see The agent loads a skill, starts a subagent or contacts an MCP server exactly when the task demands it
Takeaway Skills, subagents and MCP expand capability but must earn their cost through proven necessity
Check What three conditions trigger the activation of a skill, subagent or MCP within the AI layer?
Cost Skills, subagents and MCP all consume context and tokens. Their value is real but conditional — the discipline is adding them late, not early.

2.14 Run your own Gitea server

Gitea ships as a single Go binary (or one Docker container) with no required external services — SQLite is enough for a small team. Self-hosting means your code, history, and CI logs never leave hardware you control.

Do this first Run CI automatically on each push

Stand up a self‑hosted Gitea instance with a single Docker command and the web installer.

Try

docker run -d --name=gitea -p 3000:3000 -p 222:22 -v /var/lib/gitea:/data -e USER_UID=1000 -e USER_GID=1000 gitea/gitea:latest

Then open http://:3000 and complete the install wizard — SQLite is fine to start, swap in Postgres later if you outgrow it.

The official Gitea documentation page 'Installation with Docker', showing the docker compose setup and the docker.gitea.com/gitea:latest image — **One container, your infrastructure** — Gitea's official Docker install guide: a compose file and the gitea:latest image are the whole setup. Credit: docs.gitea.com ↗

Run the container — execute the provided docker run command to start Gitea with a persistent volume.
Open your browser — navigate to http://localhost:3000.
Complete the install wizard — select Database Type, fill in Admin Username and Password, then click Install Gitea.

You'll see The Gitea install wizard at http://localhost:3000, followed by a functional repository forge after you submit it.
Takeaway Self‑hosting is just one Docker command and a short wizard, keeping everything inside your own infrastructure
Check What three steps must you follow to stand up a self‑hosted Gitea instance using Docker and complete the install wizard?
Cost Self-hosted Gitea is free (MIT license) — you pay only for the server it runs on. Gitea Cloud (managed) starts around $9.50/month if you'd rather not run the box yourself.

2.15 Assign an Issue to Copilot and review its pull request

The Copilot coding agent is GitHub's autonomous AI contributor: assign it a GitHub Issue like you would a teammate, and it works in an isolated sandbox on its own copilot/* branch — plans the task into a checklist, writes code, runs tests, pushes commits — then opens a pull request for you to review. It runs on GitHub Actions infrastructure and cannot touch main or any protected branch directly. Beyond the coding agent, GitHub's official MCP server (github.com/github/github-mcp-server) lets any MCP-compatible AI tool — Claude included — read and write repos, Issues, and PRs directly, which is how agents outside GitHub's own UI can work the same loop.

Do this first File a scoped issue and track it on a project board·Run a CI workflow on every push

Create a scoped Issue, let Copilot generate a PR, and approve the changes

Try

Open (or reuse) an Issue with one concrete, scoped task — e.g. 'Add input validation to load_csv()'. In the Assignees panel, assign it to Copilot. It reacts with an eyes emoji, opens a draft pull request within a minute or two, and starts working — check back to watch its checklist fill in.

Coding agent needs a Copilot Pro, Business, or Enterprise seat — it isn't included on the free completions-only tier.

The GitHub Copilot coding agent working on an assigned task, showing its session and a pull request it is preparing — **The agent works like a remote teammate** — assigned an Issue, it opens a pull request and pushes commits on its own copilot/* branch for you to review. Credit: github.blog ↗

Write a detailed work‑order in the Issue description specifying the function, file or behaviour and acceptance criteria
Select Copilot in the Assignee field to assign the Issue to the coding agent
Open the generated PR via the Pull requests tab, read the diff and add feedback using the Comment box, then approve when satisfied

You'll see A pull request linked to your Issue with a task checklist that fills in as commits are pushed
Takeaway An Issue can act as a work order that an AI agent turns into a reviewable pull request without touching the main branch
Check Which three actions are required to create an Issue, assign it to Copilot, and review the automatically generated pull request?
Cost Coding agent is included in Copilot Pro ($10/mo), Business, and Enterprise — not the free tier — and runs draw from your premium-request quota. Note: GitHub paused new sign-ups for the free student Copilot plan in April 2026; check education.github.com/pack for current availability.

2.16 Run an AI‑driven feature development loop

The prime → plan → implement → validate sequence orchestrates a full ticket lifecycle driven by AI commands.

Do this first Add skills, subagents and MCP only when required

Deliver a real ticket by executing prime → plan → implement → validate and improve the AI layer from any mistakes

Tryrun ticket 42 end‑to‑end: prime && plan && implement && validate

Paste the command into the Command Console of the building‑complex‑codebases tool and press Enter; watch for any error messages so you can add a rule to CLAUDE.md when something fails.

Select a real ticket from your repository
Run the prime command to initialise the AI agent for the ticket
Execute the plan command to generate an implementation plan
Apply the implement command to create the code changes
Validate the result with the validate command
If a mistake occurs, edit CLAUDE.md to add a rule or tighten a command

You'll see The feature appears in the codebase after passing all four stages, and CLAUDE.md contains new rules added during the run
Takeaway Every error becomes a permanent system fix that compounds the agent’s reliability
Check How does executing the prime → plan → implement → validate command sequence guarantee that a real ticket is fully developed and that any mistakes are turned into permanent CLAUDE.md rules?
Cost The loop has a setup cost, but it's front-loaded: the more you run it, the more your rules and commands carry the work, and the less each task costs you.

3You’ll know it worked 53 checkable outcomes in this chapter

✓The feature is merged and passes all lint, type, and test checks
✓All unit tests pass after adding the feature and no existing workflow fails
✓The feature is merged or deployed after successfully completing all four stages without manual intervention
✓The assignee's avatar appears on the issue card in the list view
✓The new Issue appears in the repository's Issues list with the entered title and body
✓Logging into http://<host_ip>:3000 with the admin credentials shows the dashboard; the database files appear in `./data/gitea.db` if SQLite is used
✓The main branch shows the new commit and the PR is listed as “Merged” in the repository’s Pull Requests tab
✓The repo appears under your profile with the chosen name

53 outcomes in all — one per recipe below.

4FAQ, Tips & How-to 88

one problem, one solution, one action

Internal tools & ops7

How-to

Claude Code Founder +2

Adding code to an unfamiliar repo

A merged change that matches the codebase conventions — and a plan + checks you could hand to anyone.