A team, an agent that writes code, and the gates around it: context in CLAUDE.md, enforcement in hooks, roles in subagents, checks in Actions, review by Claude and by owners, rules on main. Built from one example project you can download.
Proves the stages: Build · Test · Release. Moved here from the test center, where the tests it runs still live.
The shape
The agent writes. The repository decides.
A team using Claude Code on GitHub does not need a new process; it needs the existing one made explicit and enforced by the repository, because an agent follows what is enforced and only reads what is suggested. Eight stages, each a file in the example project below.
The example project is acme-checkout: the pricing module, orders API, bot and checkout page from the Examples page, with the files that run them in a team. 68 files, all real; download them below.
The repository
Every file, as committed
Click a file to read it. The workflows were taken from the official documentation where one exists and are noted as such in their first lines; the hooks, agents, gates and passports are ours and ran against this code on 2026-10-25.
CLAUDE.md
# acme-checkout
A small checkout service: a pricing module, an orders API, a support bot and a checkout page.
This file is context for Claude Code; the hooks in `.claude/settings.json` are the enforcement.
## Commands
- Unit and property tests: `pytest -q`
- Grade the tests: `mutmut run && python scripts/mutation_gate.py` (fails below 80 percent killed)
- Contract tests: `schemathesis run http://127.0.0.1:8081/openapi.json --max-examples 200`
(start the API first with `uvicorn acme.app:app --port 8081 --app-dir src`)
- End to end: `cd e2e && npx playwright test`
- Evals: `cd evals && npx promptfoo eval --no-cache`
- Lint and format: `ruff check . && ruff format .`
## Rules for changes
- Every new function ships with tests, and we keep the tests that kill mutants. A test that
kills nothing is deleted, not kept for the coverage number.
- Property tests state invariants (never, always, round trip), not examples.
- The expected value in an assertion comes from `docs/` or from a person, never from running the
code and pasting what it printed. If the spec is silent, ask in the pull request.
- A healed Playwright test is a code change: commit it on its own with the reason in the message.
- Never run `terraform apply`, `tofu apply`, `git push --force` or delete directories; CI applies
and people merge. The PreToolUse hook blocks these anyway.
- Secrets come from the environment and GitHub Secrets, never from the repository.
- Each test file carries a Test Passport (`tests/*.passport.yaml`): who or what wrote it, which
spec it serves, where its expected values came from, who reviewed it, and its evidence. Update
the passport in the same pull request as the test.
## Pull requests
- One concern per pull request. Say what you changed and what proves it.
- Fill in the AI disclosure line of the pull request template.
- Code owners review `infra/`, `tests/` and `.claude/` (see `.github/CODEOWNERS`).
Made in your browser from the files above; nothing is sent anywhere.
Context and enforcement
CLAUDE.md is what the agent reads. Hooks are what always happens.
The official memory docs are plain about it: CLAUDE.md is guidance the model follows, and when something must happen every time, a hook enforces it. The project uses both, for different things.
CLAUDE.md: context
Lives at ./CLAUDE.md (or ./.claude/CLAUDE.md) for the project, ~/.claude/CLAUDE.md for the person, CLAUDE.local.md for the person's notes on this project, ignored by git.
Keep it under 200 lines; split with .claude/rules/ and @path imports when it grows.
What goes in: the commands, the conventions, the "never" list, where the spec lives. What stays out: anything that needs to be enforced.
PostToolUse with matcher Edit|Write: the file path arrives as JSON on stdin (tool_input.file_path); the hook formats it and runs the fast tests, so the agent sees a failure within seconds of causing it.
PreToolUse with matcher Bash: the command arrives as tool_input.command; exit code 2 blocks it and stderr goes back to the agent as the reason. That is how terraform apply and git push --force never run from the agent's shell.
Hooks are of type command, http, mcp_tool, prompt or agent; the project uses commands, kept in .claude/hooks/ so they are reviewed like code.
Markdown files in .claude/agents/ with frontmatter: name, description, tools (or disallowedTools), model, permissionMode, maxTurns.
The mutation grader has Read, Grep, Glob and Bash and a rule never to edit src/; the contract fuzzer may write tests and nothing else.
Playwright's planner, generator and healer are generated with npx playwright init-agents --loop=claude, together with the .mcp.json that gives them a browser; regenerate on upgrade rather than editing.
## Rules for changes
- Every new function ships with tests, and we keep the tests that kill mutants. A test that
kills nothing is deleted, not kept for the coverage number.
- Property tests state invariants (never, always, round trip), not examples.
- The expected value in an assertion comes from `docs/` or from a person, never from running the
code and pasting what it printed. If the spec is silent, ask in the pull request.
- A healed Playwright test is a code change: commit it on its own with the reason in the message.
- Never run `terraform apply`, `tofu apply`, `git push --force` or delete directories; CI applies
and people merge. The PreToolUse hook blocks these anyway.
- Secrets come from the environment and GitHub Secrets, never from the repository.
- Each test file carries a Test Passport (`tests/*.passport.yaml`): who or what wrote it, which
spec it serves, where its expected values came from, who reviewed it, and its evidence. Update
the passport in the same pull request as the test.
## Pull requests
Enforcement
.claude/hooks/guard.sh
#!/bin/bash
# PreToolUse for Bash: block the commands that must never run from an agent's shell. Exit code 2
# blocks the tool call and sends stderr back to Claude as the reason.
COMMAND=$(jq -r '.tool_input.command // empty')
if echo "$COMMAND" | grep -qE '(^|[;&| ])(terraform|tofu) +apply|git +push +(-f|--force)|rm +-rf +(/|~|\.)( |$)|git +reset +--hard|--no-verify'; then
echo "Blocked by .claude/hooks/guard.sh: '$COMMAND'. CI applies infrastructure and people merge; see CLAUDE.md." >&2
exit 2
fi
exit 0
Check, score, judge
The six jobs every pull request passes
Deterministic checks first, then scores with a bar, then the judgment calls. The person who merges reads the scores and samples the judgments; the rest is the pipeline's job. Each job's name is a required status check in the ruleset, so the two files are checked against each other by this site's build.
Job (required check)
Kind
What runs
What it proves
lint, unit, property, API
check
ruff, pytest with Hypothesis, the API regression tests
The code runs and the stated invariants hold. The fast half runs in the PostToolUse hook too, so the agent sees failures before the pull request exists.
mutation score
score
mutmut, scripts/mutation_gate.py at 80 percent
The tests prove something: a suite that kills fewer than four mutants in five fails the build, whoever wrote it.
Schemathesis against the OpenAPI schema
check
schemathesis run, 200 examples per operation, JUnit report
The API keeps its contract. This is the job that would have caught the 500 on GET /orders/0.
Playwright
check
npx playwright test, traces on failure
The checkout flow works as a user sees it. A healed locator is a code change reviewed like one.
promptfoo evals
score
npx promptfoo eval, deterministic assertions, exit code 100 on failure
The bot states the facts and keeps its persona. The provider here is deterministic; a real one needs the pass-rate gate from the nondeterministic page.
Test Passports
check
scripts/passport_check.py tests --min-grade B
Every test file says who wrote it, to which spec, with what evidence, and clears a B.
.github/workflows/ci.yml
.github/workflows/ci.yml
# The gates every pull request passes before a person reads it: check, score, judge.
# Each job is a required status check in rulesets/main.json, so nothing merges without them.
name: CI
on:
pull_request:
push:
branches: [main]
concurrency:
group: ci-${{ github.ref }}
cancel-in-progress: true
permissions:
contents: read
jobs:
check:
name: lint, unit, property, API
runs-on: ubuntu-latest
timeout-minutes: 15
steps:
- uses: actions/checkout@v6
- uses: actions/setup-python@v6
with: { python-version: "3.12" }
- run: pip install -e .[dev]
- run: ruff check . && ruff format --check .
- run: pytest --junitxml=results/junit-unit.xml
- uses: actions/upload-artifact@v5
if: always()
with: { name: junit-unit, path: results/ }
score:
name: mutation score
runs-on: ubuntu-latest
timeout-minutes: 20
steps:
- uses: actions/checkout@v6
- uses: actions/setup-python@v6
with: { python-version: "3.12" }
- run: pip install -e .[dev]
- run: mutmut run
- run: python scripts/mutation_gate.py
env: { MUTATION_MIN_SCORE: "0.80" }
contract:
name: Schemathesis against the OpenAPI schema
runs-on: ubuntu-latest
timeout-minutes: 15
steps:
- uses: actions/checkout@v6
- uses: actions/setup-python@v6
with: { python-version: "3.12" }
- run: pip install -e .[dev]
- run: |
uvicorn acme.app:app --port 8081 --app-dir src &
for i in $(seq 1 30); do curl -sf http://127.0.0.1:8081/openapi.json > /dev/null && break; sleep 1; done
- run: schemathesis run http://127.0.0.1:8081/openapi.json --max-examples 200 --continue-on-failure --report junit --report-dir results
- uses: actions/upload-artifact@v5
if: always()
with: { name: junit-contract, path: results/ }
e2e:
name: Playwright
runs-on: ubuntu-latest
timeout-minutes: 20
defaults: { run: { working-directory: e2e } }
steps:
- uses: actions/checkout@v6
- uses: actions/setup-node@v6
with: { node-version: 22 }
- run: npm ci
- run: npx playwright install --with-deps chromium
- run: npx playwright test
- uses: actions/upload-artifact@v5
if: always()
with: { name: playwright-results, path: e2e/results/ }
evals:
name: promptfoo evals
runs-on: ubuntu-latest
timeout-minutes: 10
defaults: { run: { working-directory: evals } }
steps:
- uses: actions/checkout@v6
- uses: actions/setup-node@v6
with: { node-version: 22 }
- uses: actions/setup-python@v6
with: { python-version: "3.12" }
# the provider here is deterministic, so no model key is needed; a real bot reads its key
# from a GitHub Secret passed as env, never from the repository
- run: npx --yes promptfoo@latest eval --no-cache --output results.json
passports:
name: Test Passports
runs-on: ubuntu-latest
timeout-minutes: 5
steps:
- uses: actions/checkout@v6
- uses: actions/setup-python@v6
with: { python-version: "3.12" }
- run: pip install pyyaml
- run: python scripts/passport_check.py tests --min-grade B
.github/workflows/nightly.yml: the soak and the MCP gates
.github/workflows/nightly.yml
# What does not belong on every pull request: the soak and the MCP gates, nightly against the
# test deployment. A threshold breach here opens an issue through the step summary.
name: Nightly
on:
schedule:
- cron: "17 3 * * *"
workflow_dispatch:
permissions:
contents: read
jobs:
soak:
runs-on: ubuntu-latest
timeout-minutes: 60
steps:
- uses: actions/checkout@v6
- uses: actions/setup-python@v6
with: { python-version: "3.12" }
- run: pip install -e .[dev]
- run: |
uvicorn acme.app:app --port 8081 --app-dir src &
sleep 2
# 30 minutes at a steady 15 users: the soak profile from the load example; p95 and the
# failure ratio are read from the CSV by the step that follows
- run: locust --headless --users 15 --spawn-rate 1 -H http://127.0.0.1:8081 -f tests/locustfile.py --run-time 30m --only-summary --csv results/soak
- run: python scripts/soak_gate.py results/soak_stats.csv
mcp-gates:
runs-on: ubuntu-latest
timeout-minutes: 10
steps:
- uses: actions/checkout@v6
- uses: actions/setup-node@v6
with: { node-version: 22 }
- run: npm i --no-save @modelcontextprotocol/server-filesystem @modelcontextprotocol/inspector
- run: |
mkdir -p docs
echo "refund policy: 30 days" > docs/policy.txt
bash scripts/mcp_gates.sh
.github/workflows/deploy.yml: the push to main, from build to canary
.github/workflows/deploy.yml
# The second trigger: the push to main. Build once, attest, scan, deploy to staging through OIDC,
# verify where variance is allowed, wait for a person at the production environment, go out as a
# canary, draft the release notes. The animated version is on the Sample diagrams page.
name: Deploy
on:
push:
branches: [main]
concurrency:
group: deploy-main
cancel-in-progress: false # a deploy in flight finishes; the next waits its turn
permissions:
contents: read
jobs:
build:
name: build once, attest
runs-on: ubuntu-latest
timeout-minutes: 20
permissions:
contents: read
packages: write
id-token: write
attestations: write
outputs:
image: ${{ steps.meta.outputs.image }}
steps:
- uses: actions/checkout@v6
- uses: actions/setup-python@v6
with: { python-version: "3.12" }
- id: meta
run: echo "image=ghcr.io/${{ github.repository }}:${{ github.sha }}" >> "$GITHUB_OUTPUT"
- run: pip install build && python -m build
- name: Generate artifact attestation
uses: actions/attest@v4
with:
subject-path: 'dist/*'
- run: echo "${{ secrets.GITHUB_TOKEN }}" | docker login ghcr.io -u "${{ github.actor }}" --password-stdin
- run: docker build -t "${{ steps.meta.outputs.image }}" . && docker push "${{ steps.meta.outputs.image }}"
- uses: actions/upload-artifact@v5
with: { name: dist, path: dist/ }
scan:
name: scan
needs: build
runs-on: ubuntu-latest
timeout-minutes: 15
steps:
- uses: actions/checkout@v6
- uses: actions/setup-python@v6
with: { python-version: "3.12" }
- run: pip install checkov bandit
- run: bandit -q -r src
- run: checkov -d infra --framework terraform --quiet --compact --config-file infra/.checkov.yaml
staging:
name: deploy staging
needs: [build, scan]
runs-on: ubuntu-latest
timeout-minutes: 15
environment:
name: staging
url: https://staging.shop.example.test
permissions:
id-token: write
contents: read
steps:
- uses: actions/checkout@v6
# the OIDC token is exchanged for a short-lived credential; no cloud key is stored in GitHub
- uses: aws-actions/configure-aws-credentials@v4
with:
role-to-assume: ${{ vars.STAGING_DEPLOY_ROLE }}
aws-region: ca-central-1
- run: ./deploy/deploy.sh staging "${{ needs.build.outputs.image }}"
verify:
name: verify in staging
needs: [build, staging]
runs-on: ubuntu-latest
timeout-minutes: 30
env:
BASE_URL: https://staging.shop.example.test
steps:
- uses: actions/checkout@v6
- uses: actions/setup-node@v6
with: { node-version: 22 }
- run: cd e2e && npm ci && npx playwright install --with-deps chromium && npx playwright test
- uses: grafana/setup-k6-action@v1
- run: k6 run load/smoke.js # thresholds in the script: p(95)<500, failures<1%
# the real model answers here; the pass rate, not zero failures, is the gate
- run: cd evals && PROMPTFOO_PASS_RATE_THRESHOLD=95 npx --yes promptfoo@latest eval --no-cache --repeat 5
production:
name: deploy production
needs: [build, verify]
runs-on: ubuntu-latest
timeout-minutes: 30
environment:
name: production # required reviewers and the wait timer are set on the environment
url: https://shop.example.test
permissions:
id-token: write
contents: read
steps:
- uses: actions/checkout@v6
- uses: aws-actions/configure-aws-credentials@v4
with:
role-to-assume: ${{ vars.PRODUCTION_DEPLOY_ROLE }}
aws-region: ca-central-1
- run: ./deploy/deploy.sh production "${{ needs.build.outputs.image }}" --canary 10
- run: ./deploy/smoke.sh production
- run: ./deploy/deploy.sh production "${{ needs.build.outputs.image }}" --all
notes:
name: release notes, drafted
needs: production
runs-on: ubuntu-latest
timeout-minutes: 10
permissions:
contents: read
issues: read
id-token: write
steps:
- uses: anthropics/claude-code-action@v1
with:
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
prompt: "Draft release notes for the commits on main since the last tag, grouped by area, one line each; a person will edit and publish them."
claude_args: |
--max-turns 5
--allowedTools "mcp__github__list_commits"
Jenkinsfile: the same pipeline on Jenkins (not run here)
Jenkinsfile
// The same pipeline on Jenkins, as drawn on the Sample diagrams page. Declarative syntax; in a
// real setup the stages come from the shared library (vars/) and this file is a few lines.
// Written to the documented syntax (jenkins.io/doc/book/pipeline/syntax); not run here.
@Library('acme-pipeline@v3') _
pipeline {
agent none // every stage names its own agent; nothing runs on the controller
options {
timeout(time: 45, unit: 'MINUTES')
disableConcurrentBuilds()
buildDiscarder(logRotator(numToKeepStr: '30'))
}
environment {
IMAGE = "ghcr.io/acme/checkout:${env.GIT_COMMIT.take(12)}"
}
stages {
stage('Checkout') {
agent { label 'linux' }
steps { checkout scm; stash name: 'src', includes: '**/*' }
}
stage('Build') {
agent { label 'linux' }
steps { unstash 'src'; sh 'pip install -e .[dev] && python -m build'; stash name: 'dist', includes: 'dist/**' }
}
stage('Test') {
parallel {
stage('Unit and property') {
agent { label 'linux' }
steps { unstash 'src'; sh 'pytest --junitxml=results/junit.xml' }
post { always { junit 'results/junit.xml' } }
}
stage('Static analysis') {
agent { label 'linux' }
steps { unstash 'src'; sh 'ruff check . && ruff format --check . && bandit -q -r src' }
}
stage('AI test generation') {
agent { label 'linux' }
when { changeRequest() } // pull requests only
options { timeout(time: 10, unit: 'MINUTES') } // the budget
environment { ANTHROPIC_API_KEY = credentials('anthropic-api-key') }
steps {
unstash 'src'
// the agent proposes tests for the diff; mutation testing grades them; nothing is committed
sh 'claude -p "Write pytest tests for the files changed in this pull request, to docs/ and never to the implementation." --max-turns 15 --allowedTools "Read,Grep,Glob,Write"'
sh 'mutmut run && python scripts/mutation_gate.py'
sh 'git diff > results/ai-tests.patch'
archiveArtifacts artifacts: 'results/ai-tests.patch', allowEmptyArchive: true
}
}
}
}
stage('Package and image') {
agent { label 'linux' }
environment { REGISTRY = credentials('ghcr-push') } // REGISTRY_USR and REGISTRY_PSW
steps {
unstash 'src'; unstash 'dist'
sh 'echo "$REGISTRY_PSW" | docker login ghcr.io -u "$REGISTRY_USR" --password-stdin'
sh 'docker build -t "$IMAGE" . && docker push "$IMAGE"'
archiveArtifacts artifacts: 'dist/*', fingerprint: true
}
}
stage('Scan') {
agent { label 'linux' }
steps {
unstash 'src'
sh 'checkov -d infra --framework terraform --quiet --compact --config-file infra/.checkov.yaml'
sh 'trivy image --exit-code 1 --severity HIGH,CRITICAL "$IMAGE"'
}
}
stage('Deploy staging') {
when { branch 'main' }
agent { label 'deploy' }
environment { KUBECONFIG = credentials('kubeconfig-staging') }
steps { unstash 'src'; sh './deploy/deploy.sh staging "$IMAGE" --all' }
}
stage('Verify') {
when { branch 'main' }
parallel {
stage('End to end') {
agent { label 'linux' }
steps { unstash 'src'; sh 'cd e2e && npm ci && npx playwright install --with-deps chromium && BASE_URL=https://staging.shop.example.test npx playwright test' }
}
stage('Load') {
agent { label 'linux' }
steps { unstash 'src'; sh 'BASE_URL=https://staging.shop.example.test k6 run load/smoke.js' }
}
stage('Evals') {
agent { label 'linux' }
steps { unstash 'src'; sh 'cd evals && PROMPTFOO_PASS_RATE_THRESHOLD=95 npx --yes promptfoo@latest eval --no-cache --repeat 5' }
}
}
}
stage('Approve production') {
when { branch 'main' }
agent none
input {
message 'Deploy this build to production?'
ok 'Deploy'
submitter 'release-managers'
parameters { string(name: 'NOTES', defaultValue: '', description: 'Release notes, as reviewed') }
}
steps { echo "Approved. Notes: ${NOTES}" }
}
stage('Deploy production') {
when { branch 'main' }
agent { label 'deploy' }
environment { KUBECONFIG = credentials('kubeconfig-production') }
steps {
unstash 'src'
sh './deploy/deploy.sh production "$IMAGE" --canary 10'
sh './deploy/smoke.sh production'
sh './deploy/deploy.sh production "$IMAGE" --all'
}
}
}
post {
failure {
// the triage station: reads the console log and the JUnit report, comments on the pull request
script { node('linux') { unstash 'src'; sh 'python scripts/triage.py --build "$BUILD_URL" --junit results/' } }
}
success {
script { if (env.BRANCH_NAME == 'main') { node('linux') { unstash 'src'; sh 'python scripts/release_notes.py --draft' } } }
}
always { echo "${currentBuild.currentResult}: ${env.JOB_NAME} #${env.BUILD_NUMBER}" }
}
}
Both pipelines are drawn and animated on the Sample diagrams page.
Claude on the pull request
Two workflows from the official docs, and what they do not do
Interactive: @claude
With no prompt input the action waits for @claude in an issue or pull request comment, then works in a checkout of the repository and reports in a comment. Setup is /install-github-app from Claude Code, or the app plus one secret (ANTHROPIC_API_KEY, or CLAUDE_CODE_OAUTH_TOKEN for a subscription) by hand.
The triggering user must have write access; bots are rejected unless listed in allowed_bots, which keeps two bots from looping.
id-token: write is needed for the app's authentication; actions: read lets Claude read CI results on the pull request.
Commits made with the default GITHUB_TOKEN do not trigger workflows, which is why the example does not pass one: Claude's pushes then run CI like anyone's.
With a prompt the action runs on the event itself. The review workflow installs the code-review plugin from the Claude Code marketplace and runs its skill with --comment, so findings land as inline comments; the claude_args line is what starts the server that posts them.
It skips drafts, closed pull requests, ones it judges trivial, and ones that already carry a Claude comment.
On public repositories GitHub withholds secrets from fork pull requests, so the review runs only on branches of the same repository.
The hosted Code Review product does the same without a workflow file on Team and Enterprise plans: it finds, verifies and ranks issues, posts a check run named "Claude Code Review", and never approves or blocks a pull request; /code-review runs the same review locally on any plan.
# Interactive mode: Claude answers @claude in issue and pull request comments. From the official
# docs (code.claude.com/docs/en/github-actions); the secret is ANTHROPIC_API_KEY or, for a
# subscription, claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}.
name: Claude Code
on:
issue_comment:
types: [created]
pull_request_review_comment:
types: [created]
jobs:
claude:
if: contains(github.event.comment.body, '@claude')
runs-on: ubuntu-latest
timeout-minutes: 30
permissions:
contents: write
pull-requests: write
issues: write
id-token: write
actions: read
steps:
- uses: actions/checkout@v6
with:
fetch-depth: 1
- uses: anthropics/claude-code-action@v1
with:
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
claude_args: "--max-turns 30"
Automated review
.github/workflows/claude-review.yml
# Automation mode: the code-review plugin reviews every pull request from a branch in this
# repository and posts inline comments. From the official docs; keep the claude_args line, it is
# what starts the server that posts the comments.
name: Code Review
on:
pull_request:
types: [opened, synchronize, ready_for_review, reopened]
jobs:
review:
runs-on: ubuntu-latest
timeout-minutes: 20
permissions:
contents: read
pull-requests: read
issues: read
id-token: write
steps:
- uses: actions/checkout@v6
with:
fetch-depth: 1
- uses: anthropics/claude-code-action@v1
with:
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
plugin_marketplaces: "https://github.com/anthropics/claude-code.git"
plugins: "code-review@claude-code-plugins"
prompt: "/code-review:code-review --comment ${{ github.repository }}/pull/${{ github.event.pull_request.number }}"
claude_args: '--allowedTools "mcp__github_inline_comment__create_inline_comment"'
Rulesets and owners
The repository's rules close the loop
A ruleset on the default branch turns the checks into a gate and the owners into reviewers. The JSON below is the shape GitHub's API and the import button accept; the rule types and parameters are the documented ones.
What main requires
pull_request: one approving review, from a code owner, after the last push, with every thread resolved; stale approvals dismissed on push.
required_status_checks with the strict policy: the six jobs, on a branch that is up to date with main.
required_signatures and required_linear_history: signed commits, no merge commits.
non_fast_forward and deletion: nobody, agent or person, force-pushes or deletes main. bypass_actors is empty on purpose.
CODEOWNERS requests reviews automatically; with require_code_owner_review in the ruleset, those reviews are required. The example makes .claude/ owned by the platform team: the agent's own rules are code, and changing them is a reviewed change.
# Code owners are requested for review automatically; the ruleset in rulesets/main.json requires
# their approval before a merge into main.
* @acme/platform
src/acme/pricing.py @acme/payments
infra/ @acme/cloud-security
tests/ @acme/quality
e2e/ @acme/quality
evals/ @acme/quality
.claude/ @acme/platform
.github/ @acme/platform
One pull request
From a 500 to a merged fix, with every gate in the way
1
The finding
Schemathesis, run from the schema alone, reports ST101 Server error and ST103 Undocumented status code on GET /orders/0: 405 generated cases, 3 unique failures, 4.7 seconds (see the example and its video).
2
The subagent
A person asks Claude Code to use the contract-fuzzer subagent. It reruns Schemathesis, writes tests/test_orders_api.py with the two failing cases, and stops: by its definition it does not touch the handler.
3
The fix and the hook
The handler checks order_id not in ORDERS and returns 404. The PostToolUse hook formats the file and runs the fast tests before the agent moves on; the guard would have refused any git push --force along the way.
4
The passport
The new test file gets tests/test_orders_api.passport.yaml: AI-authored, oracle from the contract, checked by a person, with the Schemathesis run as its origin. Without it the Test Passports job fails.
5
The pull request
The template's AI disclosure says who wrote what. The six jobs run; the review workflow posts inline comments; @acme/quality is requested because tests/ changed.
6
The merge
A person reads the scores (mutation unchanged, contract job green, passports B or better), reads the review, approves, and merges with a signed commit. Nightly, the soak and the MCP gates run against the deployment.
src/acme/app.py
@app.get("/orders/{order_id}")
def read_order(order_id: int) -> dict:
if order_id not in ORDERS:
raise HTTPException(status_code=404, detail="no such order")
return ORDERS[order_id]
This site, for real
The page you are reading was built this way
The example project is small so it can be read in one sitting. The repository behind this site is the same shape at full size: one person and Claude Code, a private GitHub repository, and gates that do not care who wrote the change.
Two scheduled jobs, one of them an agent
Every morning at 6:30 Toronto time a scheduled Claude task sweeps the day's AI security news into the Learning Center's data files, translates the new text, runs the tests and commits. It never pushes. At 7:00 and 8:00 the owner's own computer refreshes the headline feeds, rebuilds the site, commits and pushes what is ready. The brief the agent follows is a file in the repository (docs/DAILY.md), edited like code.
The site is a build output, and a test says so
Every page under site/ is generated from YAML. A test rebuilds the whole site and compares it with what is committed, so a hand edit to the HTML, by a person or by an agent, fails the suite. The test center's pages add their own checks: Python examples must parse, every link and fragment must resolve, every fact's source must be a link, and the house style rule against one punctuation mark is enforced by the build, not by a style guide.
Every commit says who wrote it with whom
Commits are authored by the owner and carry a Co-Authored-By trailer for Claude and a link to the session that produced them, so the question the Test Passport asks of tests is already answered for the code: who, with what, from which conversation. The commit that published this page ran 457 tests first.
From this repository's own docs/DAILY.md, tests/ and commit log as of 2026-10-25.
Secrets, permissions, cost
The parts the docs underline
Credentials
Never commit an API key or OAuth token; store it as a GitHub Secret and reference it. For an organization, one organization-level secret with an API key rather than a person's OAuth token, or no stored secret at all through workload identity federation (the action exchanges the workflow's OIDC token).
Permissions
Grant each workflow only what it needs: the review workflow reads contents and pull requests; the interactive one writes them. The app itself carries a wider permission set shared with other Claude features; a custom GitHub App with Contents, Issues and Pull requests covers the action alone.
Cost and runaway runs
--max-turns in claude_args, a workflow timeout-minutes, and a concurrency group with cancel-in-progress cap what one pull request can spend. Specific requests and a concise CLAUDE.md cost fewer turns.
Review before merge
The docs say it in one line: review Claude's changes before merging. The ruleset makes that line a rule.
AI SDLC: Claude Code with GitHub pull requests and Actions 1:13
One repository, one agent writing code, and the gates around it: CLAUDE.md for the rules, hooks for what must always happen, subagents for the tests, Actions for the checks, rulesets so nothing merges without them, and a human at the end. All the videos
The workflow files marked as taken from the docs are reproduced as published there; the project's other files are ours. Everything in acme-checkout that can run here ran on 2026-10-25: the tests (13 passed), the passport check, the hooks' syntax, and the YAML and JSON parsers.