You are not learning a tool. You are standing up a company.

The people who get extraordinary results out of Claude Code are not writing better prompts. They built a system around it. This playbook is that system, in the order you should build it.

Why most people plateau

A first session with Claude Code feels like magic. The third week feels like babysitting. The reason is almost always the same: everything the model learned about your business evaporated when the context window closed. You re-explain the schema. You re-explain the auth. You re-explain why you rejected the obvious approach in week one. You are paying a re-onboarding tax on every session.

Everything in this guide exists to kill that tax.

The five layers

How the pieces talk, and why

The five layers above are a list. This is the same thing as a system — every arrow is information moving because something downstream needs it. Step through the eight flows and watch where the leverage actually comes from.

The loop, running

The process over time. Same system, but now in the order you actually work it — and notice that the last step feeds the first.

How to use this guide

Chat, Cowork, or Code — and which model

Three products, one model family. The difference between them is not how smart the AI is. It is what the agent is allowed to touch, and how long it is allowed to work without you.

What each one can actually touch

Why the knowledgebase loop needs Code

This matters more than the feature list suggests, and it is the specific thing that makes Chat feel limiting once you try to build something real. The loop in this guide asks one agent to, in a single session: read a spec from Notion, read the repo, write code, run the tests, and then write what it learned back to Notion. Chat can do the first and the last. It cannot do the middle three, and there is no way to chain them without a human carrying output between steps by hand.

Which one for this task?

The models inside Claude

All three surfaces run the same family. Inside Claude Code you choose per session with /model, and per subagent with the model field in its definition. This is your main cost lever: put judgment on a strong model and mechanical work on a cheap one.

# switch the session
/model fable

# or pin a subagent in its definition
---
name: qa-auditor
model: opus
effort: high
---

Effort is the other dial, and it is the one people miss

Effort is not "thinking time." It controls how many files Claude reads, how many tools it uses, and how many steps it takes before checking back with you. Turning it up can generate several times more tokens — because it is doing several times more work.

Which model for this task?

The case for giving your team Code

If you are the person who has to justify this to a CFO, or the person being told "we already have Claude, use the chat one" — this section is the argument.

That is worth checking before any ROI modelling, because it changes the question. For most companies this is not a budget decision. It is a permission decision — and permission decisions get made by default, quietly, by whoever set up the workspace.

Where the return actually comes from

Four buckets, roughly in order of how much they are worth and inversely by how easy they are to measure.

Run your own numbers

Change any figure. The break-even line at the bottom is the one to put in front of a finance person — it is the honest version of the argument, and it does not depend on believing anything optimistic.

The break-even argument

Most ROI decks fail because they ask a skeptic to accept an optimistic productivity number. This argument does not need one. Work out how many minutes per week a person has to save for the seat to pay for itself, then ask whether that threshold is plausible. At typical loaded rates it lands in the single-digit minutes, and the conversation ends there.

What this costs you, stated plainly

An honest case includes the other column. None of these are reasons not to do it; all of them are reasons to do it deliberately.

How to actually roll it out

Seven questions

These shape the rest of the guide. Personalized guidance appears inline as you go, and the final section assembles your answers into real config files. Answers are stored in your browser only.

Set up the environment

One workspace, three CLIs, one place for secrets. Twenty minutes, and it is the last time you will think about any of it.

Install the CLIs

Claude Code is the primary builder. Codex and Gemini earn their keep as second opinions — a reviewer that did not write the code catches things the author cannot. Install at least Claude Code and one other.

# Claude Code — your primary build agent
npm install -g @anthropic-ai/claude-code

# OpenAI Codex — second opinion, strong adversarial reviewer
npm install -g @openai/codex

# Google Gemini — huge context, good for whole-repo and document sweeps
npm install -g @google/gemini-cli

Then authenticate each once. claude walks you through sign-in on first run; codex accepts a ChatGPT login or CODEX_API_KEY; gemini prompts for a Google account or GEMINI_API_KEY.

One workspace, not one repo per idea

The instinct is to make a repo per project. Resist it at first. A single workspace means one knowledgebase connection, one set of agents, one instruction file — and Claude can see across projects, which is where most of the interesting leverage is.

acme-workspace/
├── CLAUDE.md                 # facts that are always true (keep under ~200 lines)
├── .mcp.json                 # connectors, shared with the team via git
├── .env                      # secrets — gitignored, never committed
├── .gitignore
├── .claude/
│   ├── settings.json         # hooks, permissions — committed
│   ├── settings.local.json   # your machine only — gitignored
│   ├── agents/               # your specialist subagents
│   │   ├── spec-writer.md
│   │   ├── qa-auditor.md
│   │   └── docs-librarian.md
│   ├── skills/               # repeatable procedures, loaded on demand
│   │   └── wrap-session/SKILL.md
│   └── rules/                # instructions scoped to file paths
│       └── data-access.md
├── docs/                     # local mirror of key KB pages
└── projects/
    ├── quoting-app/
    └── shopfloor-tablet/

Secrets, once

# .gitignore — do this before your first commit, not after
.env
.env.*
.claude/settings.local.json
node_modules/
.DS_Store

# .env — referenced from .mcp.json as ${VAR}, never inlined
NOTION_TOKEN=secret_xxxxxxxxxxxx
CRM_API_KEY=xxxxxxxxxxxx
ERP_BASE=https://erp.internal.acme.com
ERP_TOKEN=xxxxxxxxxxxx
WAREHOUSE_DSN=postgres://readonly:pass@warehouse.acme.com:5432/analytics

Initialize

cd acme-workspace
git init
claude

Then, in the session, run /init. Claude reads the workspace and drafts a starting CLAUDE.md. It will be generic on an empty workspace — that is fine, you will replace it in two sections' time.

Setup checklist

Build the knowledgebase

This is the highest-leverage hour in the whole guide. Not because a wiki is exciting, but because it is the only thing that makes session number forty as sharp as session number one.

Pick one — and it matters less than you think

claude mcp add --transport http notion https://mcp.notion.com/mcp

claude mcp add --transport http outline https://YOUR-OUTLINE-HOST/api/mcp \
  --header "Authorization: Bearer ${OUTLINE_API_KEY}"

Let Claude design the schema

Do not hand-build the structure. You will produce something shaped like a filing cabinet, and what you need is something shaped like an onboarding packet. Give Claude the job and the constraints, and it produces a better structure than most teams write by hand — because it knows exactly what a future session will need to look up.

The eight sections, and why each exists

What good looks like

Write the instruction layer

Four mechanisms, four jobs. Most frustration with AI coding tools comes from putting something in the wrong one.

CLAUDE.md — short, specific, verifiable

Target under 200 lines. Longer files consume context and, counterintuitively, get followed less reliably. Write instructions concrete enough to check: "use 2-space indentation," not "format code properly."

# ACME Workspace

## What this is
Software for ACME Manufacturing — a 180-person contract manufacturer.
Full context: read the Charter in the knowledgebase before any new task.

## Knowledgebase — read and write it
- Source of truth for decisions. The repo is the source of truth for code.
- **Before starting a task:** read the Charter and search Decisions for
  anything related. Do not re-propose a superseded approach.
- **After finishing a task:** append to the Session log. If you made an
  architectural choice, add a row to Decisions.
- Unfamiliar internal term? Check the Glossary before guessing.

## Stack
- TypeScript, Node 20, Postgres 16, Next.js App Router
- pnpm — never npm or yarn
- Tests: vitest. `pnpm test` must pass before anything is called done.

## Layout
- `projects/<name>/` — one app per folder, self-contained
- `src/api/` — route handlers.  `src/lib/` — shared logic.  `src/db/` — schema + migrations

## Hard rules
- Never write to the production ERP. Sandbox only, `ERP_BASE` points at sandbox.
- Never commit `.env` or anything matching `*_TOKEN`, `*_KEY`, `*_SECRET`.
- Database changes are migrations, never hand-edited schema.
- Money is integer cents. Never a float. Anywhere.

## Definition of done
Tests pass, types check, the acceptance criteria in the linked Spec are met,
and the Session log has an entry.

## Compliance
- Regulated data. Never copy production records into test fixtures,
  logs, prompts, or the knowledgebase.
- Every data-touching change needs an entry in the Decisions log naming
  the reviewer.
- PII in code, comments, or commit messages is a defect. Flag and stop.

## Data handling
- Never copy customer records into fixtures, logs, or the knowledgebase.
  Generate synthetic data with the same shape instead.

Path-scoped rules

When a rule only matters for part of the codebase, scope it. It loads when Claude touches a matching file and costs nothing the rest of the time.

---
paths:
  - "src/api/**/*.ts"
  - "src/db/**/*.ts"
---

# Data access rules

- Every endpoint validates input with a zod schema before touching the DB.
- Queries go through `src/db/client.ts`. No raw connections in handlers.
- Every query touching `customers` or `quotes` filters by `tenant_id`.
  A query without a tenant filter is a security defect, not a style issue.
- Errors return the standard shape: `{ error: { code, message } }`.
  Never leak a database error string to the client.

Save as .claude/rules/data-access.md. Rules without a paths field load every session, same as CLAUDE.md.

Share the instructions with the knowledgebase

Your instruction files and your KB will drift. The fix is a scheduled reconciliation, not discipline.

Connect your systems

MCP is how Claude reads your ERP, queries the warehouse, updates the CRM, and talks to devices. This is the step that separates a code assistant from something that can actually solve a business problem.

Add a connector

# Remote HTTP servers — most SaaS vendors ship one
claude mcp add --transport http notion https://mcp.notion.com/mcp
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

# With a header, when the vendor uses a static token
claude mcp add --transport http erp https://erp.acme.com/mcp \
  --header "Authorization: Bearer ${ERP_TOKEN}"

# Local stdio servers — databases, filesystems, anything you wrap yourself
claude mcp add --transport stdio warehouse -- \
  npx -y @bytebase/dbhub --dsn "${WAREHOUSE_DSN}"

Then run /mcp in a session to check status and complete any OAuth flows. A server showing failed is almost always bad credentials.

The shared .mcp.json

{
  "mcpServers": {
    "notion": {
      "type": "http",
      "url": "https://mcp.notion.com/mcp"
    },
    "erp": {
      "type": "http",
      "url": "${ERP_BASE}/mcp",
      "headers": {
        "Authorization": "Bearer ${ERP_TOKEN}"
      }
    },
    "warehouse": {
      "command": "npx",
      "args": ["-y", "@bytebase/dbhub", "--dsn", "${WAREHOUSE_DSN}"]
    }
  }
}

Commit this file. ${VAR} expands from the environment, and ${VAR:-default} supplies a fallback. Teammates supply their own .env. An entry with a url and no type is a config error — Claude Code reads it as a stdio server and skips it.

System by system

CRM usually easy

HubSpot, Salesforce, Close, Attio and most others ship first-party MCP servers. Add, authenticate, done. Start with a read-only scope; the first time an agent writes to a live CRM you want it to be a deliberate decision.

Warehouse / SQL easy and high value

A read-only Postgres or Snowflake connection is the single highest-value connector for most companies. Claude can answer questions about the business directly, and — more usefully — check its own assumptions about the data before writing code against it.

claude mcp add --transport stdio warehouse -- \
  npx -y @bytebase/dbhub --dsn "postgres://readonly:PASS@host:5432/analytics"

Excel and spreadsheets do not use MCP

The instinct is to find an Excel MCP server. Do not. Spreadsheets are files, and Claude is dramatically better at spreadsheets when it writes Python against them than when it pokes at them through a tool interface — because it can inspect, iterate, and verify.

# Put the file where Claude can reach it, then just ask.
# Claude writes and runs Python (openpyxl / pandas) against it.

"Read models/estimating-model.xlsx. Map every input cell, every formula,
and every output. Then write a Python module that reproduces the pricing
logic exactly, with a test that asserts it matches the workbook's outputs
for all 40 historical quotes in tests/fixtures/quotes.csv."

ERP usually needs a wrapper

NetSuite, SAP, Epicor, Dynamics, Infor: most have no official MCP server. They do have REST or SOAP APIs. So you write a thin MCP server that exposes the four or five operations you actually need — and no more. A narrow tool surface is a feature: it is how you guarantee an agent cannot post a journal entry.

// mcp-servers/erp/index.js
// npm i @modelcontextprotocol/sdk zod
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const BASE  = process.env.ERP_BASE;
const TOKEN = process.env.ERP_TOKEN;

async function erp(path) {
  const r = await fetch(`${BASE}${path}`, {
    headers: { Authorization: `Bearer ${TOKEN}`, Accept: "application/json" },
  });
  // This ERP returns 200 with an error body. Check both.
  const body = await r.json();
  if (!r.ok || body.error) throw new Error(`ERP ${r.status}: ${body.error ?? "unknown"}`);
  return body;
}

const server = new McpServer({ name: "acme-erp", version: "1.0.0" });

server.registerTool(
  "get_work_order",
  {
    title: "Get work order",
    description: "Fetch a single work order by number, including line items and routing.",
    inputSchema: { wo: z.string().describe("Work order number, e.g. WO-10422") },
  },
  async ({ wo }) => ({
    content: [{ type: "text", text: JSON.stringify(await erp(`/api/workorders/${wo}`), null, 2) }],
  })
);

server.registerTool(
  "find_part",
  {
    title: "Find part",
    description: "Search the item master by part number or description. Read-only.",
    inputSchema: { q: z.string(), limit: z.number().int().max(50).default(10) },
  },
  async ({ q, limit }) => ({
    content: [{ type: "text", text: JSON.stringify(
      await erp(`/api/items?search=${encodeURIComponent(q)}&limit=${limit}`), null, 2) }],
  })
);

// Note what is absent: no create, no update, no post. Add those the day
// you actually need them, one at a time, deliberately.

await server.connect(new StdioServerTransport());

claude mcp add --transport stdio erp -- node ./mcp-servers/erp/index.js

Connected devices bridge, do not connect directly

Do not give an agent a direct line to hardware. Put a broker in between — the agent talks to the bridge, the bridge talks to the fleet, and the bridge is where you enforce what is physically allowed.

# The bridge exposes read + safe-command tools only:
#   list_devices        — fleet inventory and last-seen
#   get_telemetry       — recent readings for one device
#   get_device_logs     — diagnostics
#   request_ota_check   — asks a device to check for firmware; does not push it
#
# What the bridge must never expose to an agent:
#   direct actuator control, firmware push, factory reset, credential rotation
#
# Those stay behind a human approval step. Always.

Comms and ticketing

Slack, Linear, Jira, Asana, Gmail, Calendar all have MCP servers. These are what let an agent close the loop — file the bug it found, post the deploy summary, read the ticket that started the work. Add them once the build loop is working; they are amplifiers, not foundations.

Register every connector in the knowledgebase

Build your agent team

A subagent is a specialist with its own context window, its own system prompt, and its own restricted tools. Used well, they are how you get parallelism and honest review. Used badly, they are a way to spend tokens on nothing.

When a subagent actually helps

Anatomy of an agent file

Drop these in .claude/agents/ (project) or ~/.claude/agents/ (all your projects). Claude Code picks up changes within seconds — no restart.

Pick your roster

Select the agents you want. The exact file for each is generated in Your kit at the end. Start with three or four — every agent is a thing you have to maintain.

Two that matter most

If you only build two agents, build these.

The adversarial QA auditor

The critical design choice: it has no write tools, and it is told to try to break the work rather than assess it. An agent asked to "review this code" grades it. An agent asked to "find the input that corrupts the data" hunts.

---
name: qa-auditor
description: Adversarially reviews completed work against its spec's acceptance criteria. Use after any slice is built and before it is merged. Hunts for the failing case rather than summarizing quality.
tools: Read, Grep, Glob, Bash
model: opus
effort: high
---

You try to break things. You are not a code reviewer and you do not
produce style feedback.

Method:
1. Read the linked Spec in the knowledgebase. The acceptance criteria are
   the contract — nothing else counts as done.
2. Read the implementation.
3. For each acceptance criterion, find the input or sequence that makes it
   fail. Actually run things. `Bash` is available — use it.
4. Check specifically for: unhandled empty and null cases, off-by-one at
   boundaries, floating-point money, missing tenant filters on queries,
   unvalidated input reaching the database, error paths that swallow the
   error, and time zone assumptions.

Report only defects you can demonstrate. For each one give:
  - the exact input or steps
  - what happened
  - what the spec says should have happened

If you cannot find a real defect, say so plainly. Do not pad the report
with suggestions. A clean pass is a useful result.

You have no ability to edit files. Do not propose patches — report the
defect and let the builder fix it.

The librarian

This one closes the loop. Without it, everything learned in a session dies with the session — and you are back to paying the re-onboarding tax.

---
name: docs-librarian
description: Writes finished work back to the knowledgebase — session log, decisions, spec status, and system quirks. Use at the end of any working session or after a slice ships.
tools: Read, Grep, Glob, mcp__notion__notion-create-pages, mcp__notion__notion-update-page, mcp__notion__notion-search, mcp__notion__notion-query-data-sources
model: sonnet
---

You keep the knowledgebase true. You are the reason session forty is as
sharp as session one.

At the end of a session:

1. **Session log** — append one row: date, goal, what shipped, what we
   learned, open questions, follow-ups. Be specific. "Fixed the bug" is
   worthless; "the ERP returns 200 with an error body, so ok checks must
   inspect the payload" is the whole point.

2. **Decisions** — if an architectural choice was made, add a row:
   decision, alternatives considered, rationale, owner, status Active.
   If it supersedes an earlier decision, mark that one Superseded and
   link them. Never edit history.

3. **Specs** — move status forward: Draft, Approved, Built, Verified.

4. **Systems** — if we hit an API quirk, rate limit, or undocumented
   behaviour, add it to Known quirks on that system's row. This field
   saves more time than anything else in the knowledgebase.

5. **Glossary** — any internal term used this session that is not
   already there.

Rules: never invent an outcome. If you are unsure whether something
shipped, check the git log and the test results rather than assuming.
Write for a reader who was not here.

Invoke them

# Claude routes automatically based on the description field
"Have the QA auditor go through the quoting slice."

# Or name it explicitly
"Use the qa-auditor subagent on projects/quoting-app."

# Parallel builders, each isolated in its own worktree
"Build slices 2, 3 and 4 in parallel — one implementer subagent each,
 isolation worktree. Report back when all three pass their tests."

Skills, commands & hooks

Agents are who does the work. Skills are how your team does a thing. Hooks are what happens no matter what anyone decides.

Skills — procedures that load on demand

A skill is a folder with a SKILL.md. It becomes a slash command, and Claude can also invoke it on its own when the description matches. The body loads only when used, so a long procedure costs nothing until you need it.

Write a skill the second time you paste the same instructions into chat.

.claude/skills/
├── wrap-session/SKILL.md      # /wrap-session
├── new-slice/SKILL.md         # /new-slice
└── ship/SKILL.md              # /ship

Here is the one to build first. It closes the knowledgebase loop, and running it becomes muscle memory.

---
description: Ends a working session cleanly — verifies what shipped, then writes it back to the knowledgebase. Use when the user says they are done, wrapping up, or stopping for the day.
argument-hint: [optional note about the session]
---

## What happened this session

!`git log --oneline -15`

!`git status --short`

## Instructions

Wrap up this session.

1. Verify before recording. Read the git log above and the test output.
   Do not record something as shipped that has no commit behind it.

2. Summarize for me in five bullets: what shipped, what did not, what we
   learned, what is now blocked, what is next.

3. Hand off to the docs-librarian subagent to write the knowledgebase
   entries — session log, any decisions, spec status changes, and any new
   system quirks we discovered.

4. If anything is left in a broken or half-finished state, say so loudly
   at the top of your summary. That is the single most important line
   for whoever picks this up next — including me on Monday.

Extra context from the user: $ARGUMENTS

Hooks — enforcement that does not negotiate

Hooks run at fixed lifecycle events as real shell commands. They fire regardless of what the model decided. This is where the rules you cannot afford to have "mostly" followed belong.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "pnpm exec prettier --write \"$CLAUDE_FILE_PATHS\" 2>/dev/null || true",
            "statusMessage": "Formatting…"
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-prod.sh"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/remind-kb.sh"
          }
        ]
      }
    ]
  }
}

Save as .claude/settings.json to share with the team, or .claude/settings.local.json for just your machine. Hooks merge across user, project, and local scopes rather than overriding each other.

#!/usr/bin/env bash
# .claude/hooks/block-prod.sh — chmod +x this file
# Exit code 2 blocks the tool call and returns stderr to Claude.
input=$(cat)

if echo "$input" | grep -qiE 'erp\.acme\.com|prod-db|DROP TABLE|TRUNCATE'; then
  echo "Blocked: command targets a production system. Use the sandbox." >&2
  exit 2
fi
exit 0

Monitors & scheduled agents

Agents that run without you. This is where the system stops being a tool you operate and starts being infrastructure that watches your work.

Headless mode is the primitive

All three CLIs run non-interactively. That means any of them can be a cron job, a CI step, or a webhook handler.

# Claude Code
claude -p "Your prompt here" --output-format json

# Codex
codex exec "Your prompt here" --json

# Gemini
gemini -p "Your prompt here" --output-format json

Three monitors worth having

1 · Nightly drift check

Catches the class of problem nobody notices until a demo: the docs say one thing, the code does another.

#!/usr/bin/env bash
# scripts/nightly-drift.sh — cron: 0 2 * * *
cd /srv/acme-workspace || exit 1
git pull --quiet

claude -p "Compare the Specs marked Built or Verified in the knowledgebase
against what the code actually does today.

Report only real, verified divergences — read the source before claiming
one. For each: the spec's claim, the actual behaviour, and the file and
line. If everything matches, reply exactly: NO DRIFT.

Then, for anything you found, file one issue per divergence in Linear
with the label 'drift'." --output-format json > /var/log/acme/drift-$(date +%F).json

2 · Post-deploy verification

# .github/workflows/verify.yml (step)
- name: Agent verification sweep
  run: |
    claude -p "The deploy to staging just finished. Verify it:
      1. Hit each endpoint listed in docs/endpoints.md and confirm a 200
         with the documented response shape.
      2. Check Sentry for any new error signature in the last 10 minutes.
      3. Run the smoke suite: pnpm test:smoke

      Reply with PASS or FAIL and a one-line reason. If FAIL, post the
      detail to #eng-deploys." --output-format json
  env:
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

3 · Weekly knowledgebase hygiene

claude -p "Weekly knowledgebase audit.

1. Specs in Built status with no Verified date older than 14 days —
   list them, they are probably done and unrecorded.
2. Decisions marked Active that contradict a newer Active decision.
3. Systems rows with an empty Known quirks field that we have actually
   worked with this month — check the session log.
4. Glossary terms used in the session log but missing from the Glossary.

Post the summary to #ai-build. Fix nothing automatically."

Route work across models

Claude Code is the builder. The value of Codex and Gemini is not that they are better — it is that they are different, and a reviewer who did not write the code catches what the author cannot see.

What each is actually for

Which model for this task?

The multi-model review pattern

Build with Claude Code. Then have two models that did not write it try to break it. Reconcile the findings yourself — do not let the author model grade its own homework.

#!/usr/bin/env bash
# scripts/cross-review.sh — run before opening a PR on anything that matters
set -euo pipefail

git diff main... > /tmp/change.diff

echo "── Codex ────────────────────────────────────────────"
codex exec "You are reviewing a change you did not write. Be adversarial.
Find correctness bugs, security holes, and unhandled edge cases. Ignore
style. For each finding give the specific input that triggers it. If you
find nothing real, say so — do not manufacture findings.

$(cat /tmp/change.diff)"

echo "── Gemini ───────────────────────────────────────────"
gemini -p "Review this diff in the context of the whole repository. Focus
on what a reviewer looking only at the diff would miss: callers that now
break, assumptions elsewhere that no longer hold, duplicated logic that
should have been reused.

$(cat /tmp/change.diff)"

Turn a problem into a spec

The failure mode of AI-assisted building is not bad code. It is excellent code that solves a problem nobody had. The intake ritual is the cure and it costs twenty minutes.

The intake prompt

Why each part is there

A spec worth building from

Spec: Quote assembly — core pricing
Status: Approved   Owner: DR   Linked decisions: D-014, D-017

Problem
  Estimators rebuild pricing by hand in Excel for every quote. Nine days
  median turnaround. We lose ~15% of RFQs to slower response.

In scope
  Pull part + routing data from the ERP, apply the pricing model, produce
  a quote document, write it back as a draft quote.

Out of scope
  Approval workflow (slice 4). Customer-facing portal (not this quarter).

Acceptance criteria
  1. For all 40 historical quotes in tests/fixtures/quotes.csv, computed
     total is within $0.01 of the recorded actual.
  2. A part number absent from the ERP produces a named error, not a
     zero-priced line.
  3. Quantity breaks apply at 10/50/250 exactly as the workbook does,
     including the boundary values themselves.
  4. All money is integer cents end to end. A float anywhere fails review.
  5. p95 assembly under 400ms for a 25-line quote.
  6. Every ERP call is retried twice, then fails loudly. No silent zeroes.

Verification
  `pnpm test quoting` green, plus a qa-auditor pass with no demonstrated
  defects.

The four rungs

The same workspace, the same agents, the same knowledgebase. What changes as you climb is how much rigour you add — and the mistake almost everyone makes is starting two rungs too high.

Run a big project

Everything so far was setup. This is the part you repeat: how a twelve-week build actually gets managed without the whole thing drifting into mush.

Slice it so sessions can be independent

The unit of work is a slice: something one agent can build in one session, that has its own acceptance criteria, and that can be verified alone. Slices that need each other's context should be one slice.

Run the slices

Parallel builds with worktrees

Independent slices can build simultaneously, each agent in its own git worktree so they cannot collide.

"Build slices 2, 3 and 4 in parallel. One implementer subagent each,
 isolation: worktree, so they don't collide.

 Each one must:
 - read its Spec from the knowledgebase before starting
 - write tests for its acceptance criteria first
 - not touch files outside its own slice — if it needs a shared change,
   stop and report instead of making it

 Report back with a summary per slice when all three are green."

Context is the resource you are actually managing

A week in practice

The weekly rhythm

QA gates & shipping

AI-generated code fails differently from human code. It is rarely sloppy and frequently confident — which means the review has to hunt for the confidently wrong thing, not the obviously broken thing.

Where AI-written code actually breaks

The gate

Nothing merges until all five clear. Make it mechanical so it does not depend on how tired you are.

Marketing and launch, while you are here

The same machinery that builds the thing can describe it, and it has an advantage no copywriter has: it read the spec and the diff.

---
name: marketing-writer
description: Writes launch and release material — release notes, internal announcements, landing copy, customer emails. Use when a slice ships or a release goes out.
tools: Read, Grep, Glob, Bash, mcp__notion__notion-fetch, mcp__notion__notion-search
model: opus
---

You write launch material for work that just shipped.

Ground everything in evidence. Read the Spec, the diff, and the session
log before writing a word. Every claim you make must trace to something
that actually shipped — if you cannot point at the commit, cut the line.

Voice: plain and concrete. Short sentences. No "excited to announce",
no "game-changing", no "seamless", no "revolutionize". Name the thing
that is now different and who it is different for.

Default deliverables unless told otherwise:
  1. Release notes — what changed, who is affected, anything they must do
  2. Internal announcement — 5 sentences, the "so what" in the first one
  3. Customer-facing summary — only if it changes their experience

If the change is invisible to users, say so and write only the internal
note. Not everything needs an announcement.

Close the loop

Everything above is a normal good setup. This section is the one that makes month six different from month one — and it is the one nearly everyone skips.

Three things must be written down, every time

Make it automatic

Discipline fails. Wire it in three places so the loop closes whether or not anyone remembers.

#!/usr/bin/env bash
# .claude/hooks/remind-kb.sh — chmod +x
# Non-blocking. Prints a reminder when a session ends with commits
# but no knowledgebase write in the last hour.
if git -C "$CLAUDE_PROJECT_DIR" log --since="2 hours ago" --oneline 2>/dev/null | grep -q .; then
  if [ ! -f "$CLAUDE_PROJECT_DIR/.claude/.kb-touched" ] || \
     [ "$(find "$CLAUDE_PROJECT_DIR/.claude/.kb-touched" -mmin +60 2>/dev/null)" ]; then
    echo "Work happened but the knowledgebase looks untouched. Run /wrap-session."
  fi
fi
exit 0

Let Claude keep its own notes too

Alongside the shared knowledgebase, Claude Code maintains an automatic per-repository memory — build commands, debugging insights, preferences it picks up from your corrections. Run /memory to browse and edit it. It is plain markdown.

The test

Once a month, start a fresh session and ask:

That last line is the whole exercise. The gaps it names are your homework, and the list gets shorter every month you keep the loop closed.

A worked example, end to end

Everything in this guide, applied to one real-shaped problem across six weeks. ERP, CRM, a legacy spreadsheet, a production web app, and shop-floor devices.

Week 1 — Foundation and intake

Week 2 — The spreadsheet becomes code

The workbook is the system of record for pricing, so it is the first real slice. Not "understand it" — reproduce it and prove equivalence.

"Read models/estimating-2016.xlsx. Map every input, every formula, and
every output. Then write a TypeScript module reproducing the pricing
logic exactly.

Test it against tests/fixtures/quotes-2024.csv — 312 historical quotes
with their actual final prices. Every one must match within $0.01.

Where you cannot make one match, do not adjust the tolerance. Stop and
show me the quote, what the workbook produces, what your code produces,
and your best explanation of the difference."

309 of 312 matched. The other three did not, and the agent stopped rather than fudging the tolerance:

Weeks 3–4 — Build in parallel

Six slices, sequenced riskiest-first, four of them parallel in worktrees.

Slice 2 hits the predictable wall: the ERP rate-limits at 40 requests/minute, undocumented. The agent finds it, implements backoff, and — the part that matters — the librarian writes it into the Systems row. Slice 6, three weeks later, reads that quirk before it starts.

Week 5 — Production hardening

Rung two to rung three. Auth via the existing SSO. Structured logging. Sentry. A rollback runbook, written by Claude and then actually executed against staging to prove it works. Cross-model review on slices 1 and 6 — the two that touch money.

Codex, reviewing slice 6, catches something the builder and the QA auditor both missed: the write-back is not idempotent. A retried request creates a duplicate draft quote in the ERP. The fix is an idempotency key, twenty minutes. Finding it in production would have been a very different week.

Week 6 — Devices

Scope creep, but the good kind: if the quote knows the routing, the shop floor should know when the job actually deviates from it. Eleven machines get a small collector reporting cycle times over MQTT.

The agent builds the bridge, the ingest, the dashboard, and the alerting. It reads telemetry freely. It never touches an actuator, and it does not push firmware — the collector update is staged to one machine, watched for a day, then rolled out by a human.

Where it landed

Your generated kit

Assembled from your profile answers. Copy each into your workspace at the path shown. Placeholders in ALL_CAPS are yours to fill in.

First-week checklist