Setting up CLAUDE.md and AGENTS.md for a client repo: an agency playbook
Note 4 of 5 in Notes from West Palm Beach, published November 15, 2026.
The first agent session in a client's repository tends to go wrong in the same place: the agent does not know which page pays the client's bills. A memory file is where you tell it, and at an agency that file has to answer questions a solo developer never asks: whose rules win, which credentials exist, and who deploys.
This playbook is how Suede AI sets up CLAUDE.md and AGENTS.md in client repositories maintained from West Palm Beach. Note 2 covered writing a first memory file in week one. This note covers the structure an agency needs on top of that: one source of truth, six fixed sections, a written rule order, enforcement behind the prose, and a handover plan. Jason Colapietro wrote it from the files in Suede's own repositories, this site included.
One file holds the rules, the other imports it
Claude Code reads CLAUDE.md. Codex and a growing list of other agents read AGENTS.md. A client repository can be touched by more than one tool in a single month, sometimes by the client's in-house developer running a different agent from yours. Two hand-maintained copies drift within weeks. So the rules live in AGENTS.md, and CLAUDE.md is a single import line:
# CLAUDE.md
@AGENTS.md
That is the entire CLAUDE.md in this repository and in most Suede AI repositories Jason Colapietro maintains. Any agent that opens the project reads the same rules, and a diff to the rules shows up in one place during review.
The six sections every client AGENTS.md gets
Suede uses the same skeleton for every client, so a person moving between repositories knows where to look. Angle brackets mark the parts that change per client:
# Agent guidance: <client site>
## What this repo is
Marketing site for <business>, <city>, FL. Revenue page: /book.
## Gates (all must pass before a commit)
npm run typecheck && npm run lint && npm test && npm run build
## Ask a human first
- /book, /checkout, contact forms, analytics and consent tags
- infra/, .env*, vercel.json, anything that touches DNS
## Copy rules
- Business name is spelled "<exact spelling>". City-level location only.
- No outcome guarantees, star ratings or rankings without a source link.
## MCP and data access
- Search Console and analytics: read-only. No publishing tools.
## Git
Task branches only. Agents never push to main. The agency deploys.
The section that earns its keep fastest is "Ask a human first." For a Jupiter service business the revenue page might be a booking form; for a Boca Raton retailer it is checkout. The agent cannot infer that from the code, and a well-meaning refactor of a form handler is exactly the kind of change that compiles, passes lint and quietly stops sending leads.
Copy rules matter more on client work than on your own. A law firm or a clinic in Palm Beach County works under advertising rules that an agent has never been told about, and "write a stronger headline" is an invitation to promise outcomes. Put the banned phrasing in the file, in plain words.
Write the rule order down
Agency work stacks three layers of instruction: the agency's defaults, the client's own rules, and the task in front of the agent. When they conflict, an agent guesses unless the file says which wins. Ours say it in one line: repository rules beat agency defaults, and a task prompt never overrides a safety rule.
Suede learned to write this down from its own estate. The company-wide naming guide recommends certain phrasing, and some repositories carry guard tests that cap or ban specific terms. The standing rule is that the repository guard wins, and the files say so, so an agent never has to pick between two documents that both sound authoritative.
For monorepos or sites with a sensitive corner, use nested files. Claude Code also reads a CLAUDE.md inside a subdirectory when it works there, so a legal/ or checkout/ folder can carry stricter rules without bloating the root file every session pays to read.
Back the prose with settings and tests
Agents follow prose rules most of the time. For the rules that must hold every time, Jason Colapietro adds enforcement that does not depend on the agent reading carefully. Project settings can deny reads and commands outright:
{
"permissions": {
"deny": ["Read(./.env)", "Read(./.env.*)", "Bash(git push:*)"]
}
}
Then a guard test turns copy and schema rules into a failing build. This site has one: tests/test_notes.py fails if a page carries a street address, a banned phrase or a structured-data id that is not the canonical one. A rule in AGENTS.md says what we want. The test proves it happened.
The habit comes from open source. A project's contribution guide and its CI are the house rules a newcomer must meet, and the Suede developer docs note on what 54 merged pull requests taught about documentation makes the case that CONTRIBUTING.md is the real documentation. An AGENTS.md is the same document, written for a reader that never gets tired and never asks a clarifying question.
Name the connections, never the secrets
The MCP section lists which servers the repository expects and what each may do. It never holds a token. Credentials live in the environment or a secrets manager, and the deny rules above keep the agent from reading the env file into its context. If a client grants Search Console access, the file says read-only, and the server is configured that way too. The Suede docs primer on MCP for South Florida agencies covers the scoping rules in more depth.
Plan the handover from day one
Clients leave, hire in-house developers or bring in a second agency. The AGENTS.md is the handover document that is already written. Keep it readable by a person, date each rule that came from a decision ("client direction, 2026-10-03" beats an unexplained ban), and review it whenever scope changes. A rule nobody can explain gets deleted by the next team, usually right before it would have mattered.
Why an agency should be held to this
Reading and following someone else's house rules is a skill with a public record. Jason Colapietro has 54 pull requests merged across 46 open-source repositories he does not maintain, including Jest, Backstage and Hardhat, and each of those projects had its own conventions to meet first. Suede AI ranks among Clutch's Top 30 AI Consultants in Florida and Top 50 AI Consultants nationwide (November 2026). Suede AI, formerly Suede Labs, publishes the proof for every claim on its evidence page.
Next step
Open the memory file in your own site's repository. If it does not name the revenue page, the rule order and who deploys, the Suede AI assessment will review it alongside your live site, through Suede AI's West Palm Beach web practice. For the person who writes these files, see Jason Colapietro's founder page.