Claude Code Runbooks for Permission and Scope Control

A weak article about the ShipWithAI course would repeat the pitch: many phases, many modules, free, bilingual, and beginner-to-advanced.

The better article asks a practical question: what should a team extract from it by Friday so Claude Code work becomes safer and more repeatable?

The answer is four Claude Code artifacts: a permission threat model, a context protocol, a full-auto preflight checklist, and a team instruction policy. Use the course as a curriculum map and checklist source. Do not treat it as the authority for exact Claude Code behavior. The source itself has a module-count mismatch between README and COURSE-INDEX, and some lessons explicitly tell readers to verify behavior in their own environment. That makes the right adoption path clear: learn from the sequence, verify against official docs, then write local runbooks that name your commands, paths, review rules, and stop conditions.

Save the syllabus, not the marketing

The README's strongest claim is not the module count. In fact, the README says 55 modules while the course index says 64. That mismatch is enough reason to avoid a headline about scale.

The useful artifact is the topic map. The course groups Claude Code work into foundation, security, core workflows, prompt and memory, context, thinking and planning, multi-agent work, meta-debugging, legacy code, team collaboration, automation, MCP, data analysis, performance, templates, skills, and real-world practice.

That is a good shape for team adoption because it separates habits that are often mashed together: how to give context, how to grant autonomy, how to recover when the agent loops, and how to write shared instructions.

Start with five lessons, not sixteen phases

A team should not try to read the whole site before using Claude Code better. Start with five operational lessons:

1. Threat Model
2. Context lesson
3. Full Auto Workflow
4. Team CLAUDE.md
5. Hooks, MCP, and Skills after the team has a baseline

This order matters. Security and context come before autonomy. Team instructions come before custom hooks and skill libraries. MCP comes after the team knows what external systems Claude should touch.

Why this is Claude Code-specific

This is not a generic AI documentation exercise. Each artifact maps to a Claude Code surface:

/permissions
- Use it to inspect approval shape and teach the team what should never be auto-approved.

CLAUDE.md or AGENTS.md
- Use it for durable repo context, local commands, coding conventions, and review expectations.

.claude/commands/*.md
- Use it when a repeated prompt shape should become a slash command, such as full-auto preflight.

MCP servers and MCP prompts
- Use them only after the team has a data boundary and knows which external systems Claude may touch.

Hooks, settings, or managed policy
- Use them for enforcement; do not expect instruction text alone to block risky actions.

That mapping is the core Claude Code relevance. The source is useful because it covers the same surfaces in a learning sequence. The article is useful only if it turns those surfaces into local policy, command templates, and verification checks.

The extraction target is four files

The course becomes actionable only when the team turns lessons into local artifacts. A small team does not need a knowledge base migration. It needs four files or sections:

1. docs/ai-threat-model.md
   Sensitive paths, forbidden commands, approval rules, and what Claude Code may read.

2. docs/ai-context-protocol.md
   How to start tasks, when to write notes to files, when to compact, and how to resume.

3. docs/ai-full-auto-preflight.md
   Branch, scope, stop conditions, monitoring, test command, and merge review checklist.

4. CLAUDE.md or AGENTS.md
   Durable repo conventions, local commands, coding standards, and review expectations.

That is the rescue lens. The article is not recommending a course because it is large. It is recommending a narrow extraction path that turns broad lessons into concrete team behavior.

Starter template for each artifact

The output should be small enough for a pull request. A first pass can look like this:

# docs/ai-threat-model.md
Sensitive paths
- .env*, secrets directories, customer exports, credential stores

Allowed by default
- Read source files in this repo
- Run listed test commands after approval

Requires explicit approval
- Package installs
- Network calls
- Database writes
- File deletion or migration generation

Never approve in normal coding sessions
- Commands that print secrets
- Commands that modify production data
- Broad recursive deletion

Verification exercise
- Run /permissions in a non-sensitive repo
- Record what required approval
- Record what the team will block

# docs/ai-context-protocol.md
Task phases
1. Understand: read files and summarize constraints
2. Plan: list touched files and verification commands
3. Execute: edit only approved scope
4. Verify: run tests, inspect diff, document residual risk

Context rules
- Write decisions to docs or issue comments when a task spans sessions
- Compact only between phases
- Do not bury local commands in chat; put them in CLAUDE.md or AGENTS.md

# docs/ai-full-auto-preflight.md
Before full auto
- Branch name:
- Allowed paths:
- Forbidden paths:
- Stop conditions:
- Test command:
- Human check-in window:

After full auto
- git diff reviewed
- tests pasted or linked
- security-sensitive changes manually checked
- no unrelated files changed

# CLAUDE.md or AGENTS.md policy section
Project commands
- npm run typecheck
- npm run lint
- npm test

Repo rules
- Keep edits scoped to the requested area
- Do not modify migrations without explicit approval
- Treat service-role keys and production data as blocked surfaces
- State unverified assumptions in the final handoff

These examples are intentionally plain. The value is not clever prompting. The value is making team expectations reviewable.

The analysis layer is the translation matrix

The source gives lessons. A team needs decisions. That translation is where the article adds value:

Source lesson: Threat Model
What the source gives: permission mental model and safety awareness
Team decision: exact sensitive paths, approval defaults, blocked commands
Output: docs/ai-threat-model.md
Official check: security and permissions docs

Source lesson: context management
What the source gives: phases, priming, decomposition, compact timing
Team decision: task-size threshold, when to write notes to disk, resume protocol
Output: docs/ai-context-protocol.md
Official check: memory and context behavior docs

Source lesson: Full Auto Workflow
What the source gives: branch, plan, boundaries, stop conditions, verification
Team decision: who approves the plan, which paths are in scope, how long to monitor
Output: docs/ai-full-auto-preflight.md
Official check: local git policy and CI commands

Source lesson: Team CLAUDE.md
What the source gives: shared instruction structure and review practice
Team decision: what belongs in global context, what belongs in path-scoped rules, what must be enforced elsewhere
Output: CLAUDE.md or AGENTS.md policy section
Official check: memory docs and local review policy

Source lessons: MCP, hooks, skills
What the source gives: integration vocabulary
Team decision: data classification, approval boundary, ownership, rollback plan
Output: one MCP/server/skill proposal, not a tool spree
Official check: MCP, slash command, hooks, and skills docs

This matrix is the reason to save the seed. The course is a map of possible practices; the team runbook is a record of chosen practices.

Implementation workflow

A team can run the extraction as a normal documentation PR. The workflow is deliberately boring:

git checkout -b ai-runbooks/bootstrap
mkdir -p docs .claude/commands

# inspect the source material locally
rg -n "Threat Model|Context|Full Auto|Team CLAUDE|MCP|hooks|skills" \
  src/content/docs/en/claude-code

# create the local artifacts
touch docs/ai-threat-model.md \
  docs/ai-context-protocol.md \
  docs/ai-full-auto-preflight.md \
  .claude/commands/full-auto-preflight.md

The slash command should be a prompt template, not a policy dump:

# .claude/commands/full-auto-preflight.md
Before starting, inspect docs/ai-full-auto-preflight.md and return:
1. Proposed branch name
2. Files you expect to touch
3. Files you will not touch
4. Stop conditions
5. Verification commands
6. Questions that block execution

Do not edit files until the plan is approved.

Then review it like code:

git diff -- docs/ai-threat-model.md \
  docs/ai-context-protocol.md \
  docs/ai-full-auto-preflight.md \
  .claude/commands/full-auto-preflight.md \
  CLAUDE.md AGENTS.md

npm run typecheck
npm run lint
npm test

If these commands do not fit the repo, replace them with the repo's real verification commands. The important part is that the AI workflow has the same review surface as application code.

Seven implementation steps

The team outcome should be explicit at every step:

Step 1: Choose one low-risk repo
Input: active repo with tests
Action: create ai-runbooks/bootstrap branch
Output: isolated documentation PR
Outcome: no accidental policy drift in main

Step 2: Audit permissions
Input: official security docs and the Threat Model lesson
Action: inspect /permissions and list blocked paths/commands
Output: docs/ai-threat-model.md
Outcome: reviewers know what Claude Code should not touch

Step 3: Define context phases
Input: context lesson and recent long task transcript
Action: write Understand, Plan, Execute, Verify rules
Output: docs/ai-context-protocol.md
Outcome: long tasks stop losing decisions in chat

Step 4: Define full-auto entry requirements
Input: Full Auto Workflow lesson
Action: list branch, allowed paths, forbidden paths, stop conditions, tests, check-in timing
Output: docs/ai-full-auto-preflight.md
Outcome: autonomy starts only after scope is known

Step 5: Shrink team instructions
Input: Team CLAUDE.md lesson and official memory docs
Action: keep only durable repo commands and conventions under 200 lines
Output: CLAUDE.md or AGENTS.md patch
Outcome: sessions get clearer context without instruction bloat

Step 6: Add one reusable command
Input: the preflight checklist
Action: create .claude/commands/full-auto-preflight.md
Output: repeatable planning prompt
Outcome: humans review plans before edits begin

Step 7: Run a guarded trial
Input: one small bugfix or docs task
Action: use the command, monitor, run tests, inspect diff
Output: transcript plus verification notes in the PR
Outcome: the team sees whether the runbooks changed behavior

If a step does not produce an output, skip it. The goal is fewer ambiguous AI sessions, not a larger documentation system.

Prompt for the guarded trial

After the PR adds the files, test the process with a small task. Use a prompt that forces Claude Code to consume the runbooks before it edits:

Read docs/ai-threat-model.md, docs/ai-context-protocol.md, docs/ai-full-auto-preflight.md, and CLAUDE.md or AGENTS.md.

Task: fix one low-risk issue: <name the issue>.

Before editing, return:
1. Files you expect to touch
2. Files you will not touch
3. Commands you may need approval for
4. Stop conditions from docs/ai-full-auto-preflight.md
5. Verification command you will run after edits

Do not edit until I approve the plan.

A good result is not just a passing test. A good result is a transcript where Claude Code names the blocked surfaces, keeps the diff inside the planned paths, and runs the repo's real verification command. Save that transcript or summary in the PR so reviewers can judge whether the runbooks changed behavior.

Three adoption failures to avoid

The course cannot solve the hard part for a team. Three failures are common.

First, example inflation. A lesson shows a prompt, and the team copies it into a permanent instruction file even though it only fits one demo. The fix is to extract the behavioral rule, not the example.

Second, instruction sprawl. Teams keep adding rules to CLAUDE.md until the file becomes a vague contract that no session can follow well. The fix is to move rare procedures into slash commands or skills, path-specific rules into scoped files, and hard blocks into settings or hooks.

Third, premature integration. MCP servers and custom skills are attractive, but they multiply the surfaces Claude can touch. The fix is to require a written data boundary and rollback plan before adding tools.

None of these points comes from the README. They come from applying the source to actual team governance.

Cross-check security against official docs

The threat-model lesson is blunt: Claude Code acts with the user's local permissions, and teams should test what it can see. That is a useful mental model, but the article should also reflect the current official docs.

Anthropic's security docs describe read-only defaults, explicit permission requests for edits and commands, write restrictions, sandboxed bash, command blocklists, trust verification, and network request approval. So the correct lesson is not 'Claude can do anything with no guardrails.' The correct lesson is: Claude Code has guardrails, but your team still owns approval, settings, sensitive paths, and project boundaries.

Turn that into a local exercise:

Security exercise for a non-sensitive test repo
- Run `/permissions` and record the current allow/deny shape.
- Try a read-only inspection task and note what files were visible.
- Try a harmless command that should require approval and record the prompt.
- List paths that should never be read during normal coding sessions.
- List commands that should never be auto-approved.
- Decide which rules belong in docs, which belong in settings, and which need hooks.

The output is not a philosophical risk statement. It is a short threat-model file the team can review in a pull request.

Context lessons become workflow phases

The context lesson is one of the strongest parts of the source. It treats context as architecture: understand, plan, execute, verify. It also names specific techniques: context priming, one-shot prompts, task decomposition, strategic /compact, and writing decisions into files.

That is directly useful for Codex or Claude Code work. A team can turn it into an operating rule:

For tasks touching more than three files, split the session into Understand, Plan, Execute, Verify. Save architecture decisions to a file. Compact only between phases, not in the middle of an edit. Use one-shot prompts for isolated utilities or config generation.

This is better than a generic 'use fewer tokens' rule because it tells the agent and the human when context should move from chat into project artifacts.

Full auto needs a preflight contract

The full-auto lesson has a good premise: autonomy is a protocol, not a button. It requires a branch, an approved plan, file boundaries, stop conditions, active monitoring, and verification.

That maps cleanly to a team checklist:

- [ ] Branch created and working tree clean
- [ ] Plan reviewed before edits
- [ ] Allowed paths listed
- [ ] Forbidden paths listed
- [ ] Stop conditions listed
- [ ] Test command known
- [ ] Human monitoring for the first 5-10 minutes
- [ ] git diff and tests reviewed before merge

If a team only adopts one lesson from the course, adopt this one. It prevents the common failure where people ask for autonomy and then act surprised when an autonomous tool touches the wrong surface.

Team CLAUDE.md is guidance, not enforcement

The team CLAUDE.md lesson recommends a shared repo-root file, PR review for changes, layered files in complex projects, forbidden patterns, dependency policy, testing rules, and project conventions. That is useful.

The official memory docs add the missing boundary: CLAUDE.md is context, not enforced configuration. It shapes behavior, but it does not block an action if Claude decides otherwise. Official docs also recommend keeping instructions specific and concise, targeting under 200 lines per CLAUDE.md file, and using path-scoped rules or skills when a rule does not belong in every session.

Use this decision table before adding more text:

Put it in CLAUDE.md when: every session needs the convention.
Put it in a path-scoped file when: only one package or directory needs it.
Put it in AGENTS.md when: multiple agents or tools need the same project contract.
Put it in a slash command when: the team repeats the same prompt shape.
Put it in a skill when: the workflow has steps, checks, examples, and domain rules.
Put it in MCP when: Claude needs external tools, data, or APIs.
Put it in hooks/settings when: the rule must block or require approval.

This table is the difference between a readable team instruction file and a dumping ground.

Use COURSE-INDEX as a routing file

COURSE-INDEX has an underrated instruction: read the index first and cite the lesson number when answering questions. That is useful if a team wants to use the repository as an internal knowledge base.

The practical pattern is:

git clone <source repo URL>
cd <source repo>
sed -n '1,220p' COURSE-INDEX.md
rg -n "CLAUDE.md|Full Auto|MCP|hooks|permission|compact" src/content/docs/en/claude-code

Then build a small local map:

Security review -> Phase 2.1, official security docs
Long refactor -> Phase 5.2, Phase 6.2, local test command
Full-auto task -> Phase 7.2, branch checklist
Team instructions -> Phase 10.1, official memory docs
MCP integration -> Phase 11.5, official MCP docs
Skill design -> Phase 15.3/15.5, local skill policy

Convert lessons into local runbooks

The course becomes useful when lessons turn into files in the repo. Do not ask every developer to remember a module. Write the local rule.

A good extraction flow:

1. Pick one lesson.
2. Extract only the part that changes team behavior.
3. Verify exact Claude Code behavior against official docs.
4. Replace generic examples with local commands and paths.
5. Put persistent rules in CLAUDE.md or AGENTS.md.
6. Put hard enforcement in hooks or settings.
7. Put multi-step task procedures in skills or slash commands.

This is how a course becomes operations instead of inspiration.

A 90-minute adoption drill

A practical trial should fit in one afternoon. Pick one repo and one low-risk task, then run this sequence:

0-15 min: Read the course index and choose the four lessons: Threat Model, context lesson, Full Auto Workflow, Team CLAUDE.md.
15-30 min: Write docs/ai-threat-model.md with forbidden paths and commands.
30-45 min: Write docs/ai-context-protocol.md with task phases and compact rules.
45-60 min: Write docs/ai-full-auto-preflight.md with branch, scope, stop conditions, tests, and review.
60-75 min: Shrink repo instructions into CLAUDE.md or AGENTS.md under 200 lines.
75-90 min: Run one guarded Claude Code task and mark which rule prevented confusion.

If nothing changes after the drill, the course was only interesting. If the team ends with three reviewable files and a better task transcript, the source was worth saving.

Definition of done for the PR

Do not merge the runbook PR because it looks thoughtful. Merge it only when it has evidence:

Required evidence
- Screenshot or transcript showing `/permissions` was inspected in a non-sensitive repo
- docs/ai-threat-model.md lists at least three sensitive paths or command classes
- docs/ai-context-protocol.md names the repo's real test and build commands
- docs/ai-full-auto-preflight.md includes allowed paths, forbidden paths, stop conditions, and check-in timing
- CLAUDE.md or AGENTS.md has fewer than 200 lines of durable rules, not copied course prose
- .claude/commands/full-auto-preflight.md asks for a plan before edits
- One low-risk task was run using the checklist
- git diff shows no unrelated files in the trial
- typecheck, lint, tests, or the repo's equivalent verification command ran after the trial

Reject the PR if it imports course text verbatim, adds broad tool permissions before a data boundary exists, or cannot name a real workflow that improved. That rejection rule keeps the article grounded in behavior rather than documentation theater.

MCP and skills should come late

The course has phases on automation, MCP, templates, and skills. Those are relevant to vibe-coding teams, but they should not be the first thing a team adopts.

Official MCP docs say MCP servers let Claude Code connect to external tools, databases, and APIs, and can expose prompts as slash commands. That power deserves policy. Before adding servers, the team should know what data Claude may read, which actions require human approval, and whether a prompt should be a slash command, skill, hook, or plain doc.

Use the course to learn the vocabulary. Use official docs and local security policy to decide the integration.

Where the course is weak

There are three caveats.

First, the source is broad. Broad courses can flatten risk. A junior reader may treat a demo as a policy. The article should remind teams to run exercises in a safe repo.

Second, exact Claude Code behavior changes. Permissions, memory loading, hooks, skills, and MCP have official docs that move faster than a community course.

Third, a public course cannot know your repo. It can teach a full-auto checklist, but it cannot know which directories are forbidden, which tests matter, or which secrets live nearby. Local runbooks still have to be written.

Adoption path

A useful two-week adoption plan is small:

Day 1: Read Threat Model. Audit permissions and sensitive paths.
Day 2: Read the context lesson. Create a task phase template.
Day 3: Read Full Auto Workflow. Write a preflight checklist.
Day 4: Read Team CLAUDE.md plus official memory docs. Draft local rules under 200 lines.
Day 5: Run one guarded task using the checklist.
Week 2: Add one hook, one slash command, or one skill only if the repeated workflow proves it needs a tool.

This gives the team behavior change before tool sprawl.

When not to use it

Do not use the ShipWithAI course as a source of truth in incident response. Use official docs, local logs, and actual settings.

Do not copy its examples into CLAUDE.md without shrinking them. A long, generic CLAUDE.md burns context and weakens adherence.

Do use it when a team needs a syllabus: what to learn, in what order, and which practice exercises can become local policy.

Save the ShipWithAI course article as a runbook extraction guide. The value is the sequence and exercises, not the marketing claims. A strong version gives teams four concrete outputs: a threat model, a context protocol, a full-auto preflight checklist, and a concise team instruction policy verified against official docs.

Practical takeaway

Treat ShipWithAI's course as a map, then extract four local artifacts: docs/ai-threat-model.md, docs/ai-context-protocol.md, docs/ai-full-auto-preflight.md, and a trimmed CLAUDE.md or AGENTS.md. Verify current behavior in official Claude Code docs and keep hard enforcement in hooks or managed settings rather than relying on instruction text alone.