Coding agents read context from files in the repo: AGENTS.md, CLAUDE.md, .cursor/rules, a docs/ folder. This recipe keeps one short instructions file in the repo and moves everything else to PlaybookOps. The agent looks up what it needs, when it needs it, and the people who own the conventions can change them without a pull request.
You'll commit three small things to the repo: the server config, the instructions, and which tools the agent may run without asking. None of them contain a key.
- 1
Each developer makes a read-only key
Each person makes their own Read-only key, named something like "Claude Code on my laptop", and adds it to their shell profile:
export PLAYBOOKOPS_API_KEY="pbo_live_…"A read-only key means the agent can look things up but can't change anything, whatever it decides to do. Because a key acts as its owner, everyone's agent sees exactly the playbooks they can.
- 2
Commit the server config
Project config files let the whole team share one setup. Each reads the key from the environment.
.mcp.jsonat the root of the repo:{ "mcpServers": { "playbookops": { "type": "http", "url": "https://mcp.playbookops.ai", "headers": { "Authorization": "Bearer ${PLAYBOOKOPS_API_KEY}" } } } }Claude Code asks each person once before using a project's servers.
- 3
Tell the agent how to use it
Put this in
AGENTS.mdat the root of the repo. Codex and Cursor read it as it is. For Claude Code, add aCLAUDE.mdcontaining@AGENTS.md.## Team knowledge lives in PlaybookOps Our conventions, runbooks and architecture notes are in PlaybookOps, not in this repo. Use the playbookops tools to read them. - At the start of a task, read the "Engineering conventions" document with read_document (id: DOCUMENT_ID) and follow it. - Before changing an area you haven't worked on in this session, look up how we do it: search_knowledge with a whole question, like "How do we write database migrations?". Read the documents that match with read_document; a passage on its own can mislead. - Don't search for every small step. Each search uses an AI credit. - If a document and the code disagree, follow the code, finish the task, and tell me which document looks out of date and why. - List the documents you relied on, with their links, in your summary. - If nothing covers a question, say so and use who_knows to suggest who to ask.DOCUMENT_IDis thecontentIdin the document's address in the app. Pin only what every task needs; everything else is better looked up. - 4
Let the lookups run without asking
Lookups are read-only, so there's no need to approve each one.
.claude/settings.json:{ "permissions": { "allow": [ "mcp__playbookops__search_knowledge", "mcp__playbookops__read_document", "mcp__playbookops__list_content", "mcp__playbookops__list_playbooks", "mcp__playbookops__who_knows" ] } }
Try it
Ask your agent for something that depends on how your team works:
- "Add a column for the customer's region to the orders table." The agent should look up how you write migrations before writing one.
- "The deploy failed with a health check timeout. What do we do?" It should find and follow the runbook, and link it.
- "Review this branch against our conventions."
What to move out of the repo
| Keep in the repo | Move to PlaybookOps |
|---|---|
| How to build, test and run the code: commands, scripts, environment setup | How the team works: conventions, review standards, release and on-call process |
| Instructions about this repo's layout | Runbooks, incident write-ups, architecture decisions |
A short AGENTS.md that points at PlaybookOps | Anything people outside engineering read or write: product notes, support playbooks, policies |
The rule of thumb: if it changes when the code changes, keep it next to the code. If it changes when the team changes its mind, put it where the team can edit it.
Next
- Move a docs repo into PlaybookOps to bring the existing
docs/folder across. - Have agents keep docs current once you trust them to suggest fixes.