First problemsCLAUDE.md and standardsYour codebasesClose
15 min opening and first problems, 60 min preparing the codebase, the rest together
0:00
Opening, then common first problems·seven problems, and what to do about each
0:15
Preparing the codebase·CLAUDE.md and standards
0:55
Break
1:00
Your codebases·baselines, legacy code, many repositories
1:20
Homework, close
1:30
End
Your world will change completely. Learning this is make or break.
Where this is going: entire epics, built autonomously overnight
Agents build everything in parallel.
Other agents check the work and send it back, many rounds over.
Thousands of tests work through green, red, repeat. Lint and type check, commit and push.
Followed from a phone. A real codebase.
You are a tool builder now. Relentless experimentation is the job.
First problems
Commonfirst problems
Seven problems teams run into first, and what to do about each.
CLAUDE.md contained wrong or missing details. /init writes a draft, not the truth.
Add what it cannot work out from the code: business terms and abbreviations from your domain, how to start the app and run one test, what not to touch. Then run /doctor prompt-audit.
Longer CLAUDE.md files are not better
.claude/rules/checkout.md (illustrative)
---
paths:
- "src/checkout/**"
---
# Checkout
- Prices are integers in cents, never floats
- Every price change gets a test in checkout.spec.ts
Keep the root file under 200 lines. For every line: would removing this cause Claude to make mistakes? If not, cut it. Rules for one area go into .claude/rules/ and load only when Claude touches those files.
Stories are not detailed enough, or the request is just "fix this"
What
The change, and where it lands.
Where to stop
"Only change the basket card. List related issues instead of fixing them."
Done
Something that can check it, with one worked example.
Ticket too thin? Have Claude interview you first. Then build from SPEC.md in a fresh session. Interview me in depth about this ticket and write a specification with acceptance criteria as test cases, so we can build it test-driven. Write it to SPEC.md.
You are starving Claude of valuable context if you do not integrate with your tools.
A screenshot instead of the Figma file. A pasted ticket instead of the tracker. Every copy-paste drops the layer names, tokens, comments and links.
Tool connections failing with certificate errors behind a company proxy? Tell Node to trust the system certificates.
Tests run over each other, and containers fight over ports.
Random ports in the test config, one command in CLAUDE.md that cleans and runs (./mvnw clean test), and a hook that shuts the test containers down when the session ends.
Your tests are more important than your existing code. The agent can rewrite the code. The tests tell it whether it was right.
Tell Claude to work test-first: write the tests, then the implementation, then run the tests.
QA engineers rock.
How do we share CLAUDE.md and the rest of the setup?
Single repo
Commit CLAUDE.md, .claude/settings.json, .claude/rules/ and .claude/skills/ to the repo. Personal preferences go in CLAUDE.local.md, not committed.
Multi repo
A plugin in a private marketplace that everyone installs. Keep the setup in one repository, versioned like code.
Where we are
01Core concepts
02TodayPreparing the codebase for agents
03Writing a good spec
04Feedback loops
05Workflow integration and code review
06Claude Code in depth
07Orchestration and subagents
08Claude Code alternatives
Session 01 explained how it works. From today on: what you change so it works for you.
Session 01: the context decides the result. Today: what you put into it on purpose.
One context window, every session
system promptCLAUDE.mdstandards and contexteverything else
This is the most important part. This is what we're working on today.
What we cover today
Advisory standardsAGENTS.md@importBaseline
.claude/rulesCLAUDE.mdpaths
Enforced standardsOpenAPILegacy code
Characterization testsMulti-repoGenerated types
Part one
YourCLAUDE.md
The file that is in every conversation.
The agent knows your codebase only through what it reads. Every convention nobody wrote down, it guesses.
CLAUDE.md
A file Claude Code puts into the context at the start of every session.
It is read on every turn. Every line has to earn its place.
What belongs in it, and what does not
Belongs
Commands it cannot guess: build, test, lint
Rules you cannot see in the code
Decisions specific to this project
Environment quirks
Leave out
What it can read from the code
Standard conventions it already knows
Long explanations and history
Anything that changes often
Under 200 lines. For each line ask: would removing it cause a mistake?
A CLAUDE.md that earns its place
CLAUDE.md (illustrative)
# Shop storefront (Nuxt 3, TypeScript)
## Commands
- pnpm dev starts the shop on :3000
- pnpm test unit tests; pnpm test:e2e runs Playwright
- pnpm lint --fix before every commit
## Rules
- Never edit src/generated/: run pnpm generate:api instead
- Prices are integers in cents, never floats
- New components follow components/ProductCard.vue
## Standards
- Before you touch a migration, read docs/standards/database.md
Correct the file, not the chat. Every correction you type twice is a line missing from CLAUDE.md.
Ask Claude to add it to CLAUDE.md, then review that change like code. If a rule is there and still ignored, the file is too long.
One file is not enough for a complex codebase. What loads, and when.
💡 Quick tip
One instruction file for every tool
CLAUDE.md
@AGENTS.md
## Claude Code only
- Use plan mode for changes under src/checkout/
Shared rules live in AGENTS.md, which other tools read too. Claude Code reads AGENTS.md on its own only when there is no CLAUDE.md.
Part two
Advisory andenforced standards
Rules the agent reads, and rules the build checks.
Standard
The rules for one topic, in their own file. CLAUDE.md or the rules say when to read which.
Three ways to connect a standard
@import
@docs/standards/api.md in CLAUDE.md. Loads at every session start.
Rule with paths
A file in .claude/rules/ with a paths field. Loads only when the agent reads a matching file.
Subfolder file
A CLAUDE.md inside the folder. Loads when the agent works there.
Most standards belong in a rule with a paths field.
Example: a database standard
.claude/rules/database.md
---
paths:
- "**/migrations/**"
- "**/*.sql"
- "src/**/repository/**"
---
# Database
- Migrations only add. Never edit one that has already run.
- New columns are nullable or have a default.
- No queries outside the repository layer.
- No data deletes in a migration without approval.
- After every change: pnpm test:db
Names only: write the ones your repository needs. Start where the agent goes wrong most.
Generating standards: first pass by the agent, the review and improvement by you is not optional!
Advisory standards ask. Enforced standards check.
Example: types generated from the OpenAPI definition
src/cart/total.ts
// Product comes from src/generated/, built from the API's OpenAPI definition
const price = product.priceGross;
// ~~~~~~~~~~// error TS2339: Property 'priceGross' does not exist on type 'Product'.// Did you mean 'grossPrice'?
If you enforce type checks, the agent cannot use a field that does not exist.
Where enforced standards come from
Generated types from OpenAPI or GraphQL schemas
Strict compiler settings
The database schema and its migration tool
Linter and formatter configuration
Architecture tests such as ArchUnit for Java
Contract tests between services
Design tokens generated from Figma
A check only helps if the agent runs it
two files, two jobs
# CLAUDE.md
After every change: pnpm typecheck
After an API change: pnpm generate:api
# .claude/settings.json
"permissions": { "deny": ["Edit(/src/generated/**)"] }
The command makes it run the check. The deny rule stops it from editing the generated types to make the error go away; that fix would be gone on the next build.
An advisory rule that is ignored is a candidate for a check.
Part three
Yourcodebases
Baselines, legacy code, many repositories.
Let's start with a baseline assessment, before you fill your repos with AI configuration
Test coverage
Build time
Ticket to merge
Open bugs
Write down where you are today. At the end of the program, we compare.
Legacy code: tests first, changes second.
Characterization tests pin down what the code does today, not what it should do.
You do not need a monorepo
one parent folder, repositories side by side
shop/ <- start Claude Code here
├── CLAUDE.md which repository does what
├── storefront-brand-a/ its own CLAUDE.md
├── storefront-brand-b/ its own CLAUDE.md
└── shop-starter/ the upstream the forks came from
The parent CLAUDE.md is the map. Working in one repository and need another? claude --add-dir ../other-repo lets the session read and edit both.
The agent cannot work on code it cannot read.
Code inside a vendor system: get it into git first. Figma: without the MCP server, the agent gets no full mockup and no frontend code. Everything else: the related repositories on disk.
Sharing the setup
In git, reviewed like code
CLAUDE.md and subfolder files
.claude/rules/
.claude/settings.json
Yours only
~/.claude/CLAUDE.md
CLAUDE.local.md, not committed
Personal preferences and shortcuts
Several repositories? Package the setup as a plugin in a private marketplace that everyone installs.
Today, in thirty seconds
Common first problems
/init writes a draft, not the truth
Interview first, then SPEC.md
Connect your tools
Tests matter more than your code
CLAUDE.md and standards
Under 200 lines
Correct the file, not the chat
Rules with a paths field
You review what the agent writes
Advisory asks, enforced checks
An ignored rule becomes a check
Your codebases
Baseline first
Legacy: tests first
One parent folder, no monorepo
The agent reads all of it
Shared in main, or in a plugin
Example homework, to be tailored to your team
Homework: a team exercise
Baseline
Take the baseline assessment. Share it, so we can track progress over the program.
Setup
Write a CLAUDE.md. Commit it to main, or publish and install a private marketplace plugin.
Standards
Implement the most relevant standards. Commit them to main, or add them to the plugin.
Share
Be ready to show it in 5 minutes: proof that it is in main, one standard that changed what the agent does, before and after, and one thing another team can copy.
Done means it is in main, or in the plugin. Not on a laptop, not on a branch. For all important repositories, as a team, before the next session.
