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.

  1. 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. 2

    Commit the server config

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

    .mcp.json at 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. 3

    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.

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

  4. 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 repoMove to PlaybookOps
How to build, test and run the code: commands, scripts, environment setupHow the team works: conventions, review standards, release and on-call process
Instructions about this repo's layoutRunbooks, incident write-ups, architecture decisions
A short AGENTS.md that points at PlaybookOpsAnything 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