# Give coding agents your playbooks

> Claude Code, Cursor and Codex look up your conventions and runbooks in PlaybookOps instead of a docs folder in the repo.

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.

### 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:

```bash
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.

### Commit the server config

Project config files let the whole team share one setup. Each reads the key from the environment.

**Claude Code**

`.mcp.json` at the root of the repo:

```json
{
  "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.

**Cursor**

`.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "playbookops": {
      "url": "https://mcp.playbookops.ai",
      "headers": { "Authorization": "Bearer ${env:PLAYBOOKOPS_API_KEY}" }
    }
  }
}
```

**Codex**

`.codex/config.toml`. Codex reads project config once you've marked the project as trusted.

```toml
[mcp_servers.playbookops]
url = "https://mcp.playbookops.ai"
bearer_token_env_var = "PLAYBOOKOPS_API_KEY"
enabled_tools = [
  "search_knowledge", "read_document", "list_content", "list_playbooks", "who_knows",
]
```

### Tell the agent how to use it

Put this in `AGENTS.md` at the root of the repo. Codex and Cursor read it as it is. For Claude Code, add a `CLAUDE.md` containing `@AGENTS.md`.

```markdown
## 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_ID` is the `contentId` in the document's address in the app. Pin only what every task needs; everything else is better looked up.

### Let the lookups run without asking

Lookups are read-only, so there's no need to approve each one.

**Claude Code**

`.claude/settings.json`:

```json
{
  "permissions": {
    "allow": [
      "mcp__playbookops__search_knowledge",
      "mcp__playbookops__read_document",
      "mcp__playbookops__list_content",
      "mcp__playbookops__list_playbooks",
      "mcp__playbookops__who_knows"
    ]
  }
}
```

**Cursor**

In Cursor's settings, find the agent's auto-run options and add the same five tools to its MCP allowlist.

**Codex**

Add `default_tools_approval_mode = "writes"` under `[mcp_servers.playbookops]`. Codex then runs read-only tools without asking.

## 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](https://developers.playbookops.ai/cookbooks/import-a-docs-repo) to bring the existing `docs/` folder across.
- [Have agents keep docs current](https://developers.playbookops.ai/cookbooks/keep-docs-current) once you trust them to suggest fixes.
