Claude Code Playbook

Prepare Claude Code

1. Open the repository in Claude Code and create (or verify) .claude/agents, .claude/prompts, .claude/commands, and .claude/sessions.
2. Copy everything from AI-toolkit/agents/, AI-toolkit/prompts/, and AI-toolkit/session-commands/ into the matching .claude/ folders. Keep the originals version-controlled so you can pull updates.
3. Drop the Claude briefing template next to your codebase root and run /init so Claude boots with project context.
4. Create an empty .claude/sessions/.current-session file and add .claude/sessions to .gitignore to protect local notes.
5. Reload Claude Code, check the sidebar, and ensure agents + prompts show in the file browser for quick @ referencing.

Keep the toolkit on a shared drive or as a Git submodule so every teammate pulls identical agent instructions.

File placement & sync strategy

• Agents: Store only the personas your team actually uses inside .claude/agents/. Leave the master catalog in AI-toolkit/agents/ and reference extras with paths such as @../AI-toolkit/agents/orchestration/tech-lead-orchestrator.md.
• Prompts: Mirror the core set (@create_brief, @plan_feature, @code_review, @write_docs) into .claude/prompts/. Keep custom prompts alongside the project so they travel with the repo.
• Session commands: Copy the markdown files from AI-toolkit/session-commands/ into .claude/commands/. Claude reads them verbatim when you run the accompanying slash command.
• Backups: Automate a daily zip of .claude/ except .claude/sessions/ so you can restore agents if someone edits them accidentally.

Kick off a new project in Claude

1. Run /project:session-start project-name and paste the request, stakeholders, and deadlines.
2. Trigger @create_brief.md to capture north-star context, then archive the output in the session log.
3. Use @plan_feature.md with the first epic and follow the embedded TODOs it creates.
4. Delegate specialist work: run /tool run agents/orchestration/tech-lead-orchestrator.md to assemble the execution graph, then loop in framework agents.
5. Establish a cadence—after each coding burst paste git status into /project:session-update, then request @code_review.md before merging.

Continue a legacy or inherited project

1. Import or recreate the latest session log (ask the prior owner for .claude/sessions/<date>.md). Use session-restorer.md to rebuild context.
2. Scan the repo with project-analyst.md and code-archaeologist.md to surface unknown dependencies and risk areas.
3. Run @plan_feature.md in “maintenance mode” (follow the bug/refactor instructions inside the prompt) to map the next safest changes.
4. Document assumptions inside /project:session-update and keep a punch list of unanswered questions for the original team.
5. Before your first deploy, run reliability-commander.md and testing-expert.md so you understand coverage gaps and rollback steps.

Recommended Claude agents by scenario

Pin your top five agents in the Claude sidebar and use /tool run ... --force when you want deterministic output without conversational drift.

Co-ordinate multi-agent runs

1. Author the playbook: Start with tech-lead-orchestrator.md to generate the execution graph. Ask for explicit agent-to-agent handoffs (e.g., “frontend-designer passes mock notes to react-component-architect”).
2. Assemble the crew: Use team-configurator.md to confirm who leads each phase, escalation paths, and communication cadence.
3. Chain specialists: Paste the orchestrator output back into Claude and call each specialist in order. Include the previous agent’s summary so context compounds.
4. Agent-controlled agents: If an agent must brief another (e.g. project-analyst.md → django-api-developer.md), ask it to run session-closer.md (or a custom “handoff” template) so the next agent receives a clear brief.
5. Quality guardrails: After the specialist loop, trigger reliability-commander.md, testing-expert.md, and brutal-critic.md to enforce process discipline before shipping.

Keep a running “agent stack” inside the session log—note which agent ran, what it produced, and who must act next. This makes restarting the chain trivial.

Sample scenario: shipping a payments webhook

1. Kickoff & planning: Run /project:session-start payments-webhook, paste the ticket, then trigger @create_brief.md followed by @plan_feature.md. Paste both outputs into the session log.
2. Multi-agent orchestration: Invoke tech-lead-orchestrator.md to map the chain (backend specialist → reviewer → QA). Let the orchestrator call djagno-api-developer.md automatically by including the plan in the chat.
3. Implementation: Execute the guided steps, running django-api-developer.md for serializers/views and testing-expert.md for pytest coverage. Paste command output from your terminal into /project:session-update.
4. Review & docs: Use @code_review.md with git diff, then let brutal-critic.md critique the patch. Finish with @write_docs.md to generate release notes and update your session summary log.
5. Close session: Run /project:session-end and attach the final agent outputs so other tools (Gemini, Codex, Cursor) are ready for the next iteration.

Each time an agent finishes, append a short “Result” block to the session log so you can replay the scenario or hand it off mid-stream.

Advanced creation & research catalogue

Foundational level

• Architecture briefs: Run @create_brief.md and api-architect.md together to transform a user story into stakeholder-ready documentation.
• Knowledge synthesis: Pair general-research-agent.md with session-closer.md to gather links, annotate findings, and store them as searchable Markdown.
• Test blueprints: Use @plan_feature.md followed by testing-expert.md to produce end-to-end test checklists for QA teams.

Intermediate level

• Content production: Feed meeting transcripts into content-writer.md to generate customer emails, tutorials, or release notes. Refine tone with vibe-coding-coach.md.
• Process automation: Ask reliability-commander.md to generate tailored readiness checklists, then embed the checklist in your workflow playbook via Claude’s file editor.
• Research digests: Use general-research-agent.md → session-closer.md → @write_docs.md to move from raw links to a polished market or technical report.

Advanced level

• Large-scale refactors: Combine project-analyst.md, code-archaeologist.md, and code-refactorer.md with orchestrated handoffs to plan multi-sprint migrations.
• Compliance & audit packs: Run reliability-commander.md, security-auditor.md, and session-closer.md in sequence, then have @write_docs.md produce audit-ready PDFs.
• Cross-tool controller: Use Claude to command Gemini or Codex runs—paste Claude-generated scripts into those CLIs, pull their outputs back, and let Claude consolidate them into strategy documents.

Claude does not generate images or video directly; when visual assets are needed, have Claude draft structured prompts for Gemini (image) or external tooling, then weave the returned assets into your docs.

Prompt patterns that stick

Terminal power moves inside Claude

• Command history: Claude remembers recent slash commands—type / and arrow up to reuse /project:session-update templates.
• Snippet insertion: Save frequently used shell commands (lint/test scripts) as prompt snippets and drag them into the chat when you want Claude to execute them.
• Side-by-side diffs: After Claude suggests code, ask it to produce a git apply-ready patch so you can paste straight into your terminal.
• Automate guardrails: Pair Claude with local tooling like pre-commit, ruff, eslint, pytest, and npm test. Have Claude draft the commands; you run them and paste the logs back for analysis.

Design, documentation, and collaboration best practices

• Design handoff: Use frontend-designer.md to convert Figma specs into component architecture. Follow up with vibe-coding-coach.md for tone/branding notes.
• Docs first: Start README amendments inside Claude with documentation-specialist.md, then share the draft via @write_docs.md for consistent formatting.
• Cross-tool sync: After each major Claude action, mirror the state into Gemini, Codex, OpenCode, or Cursor by copying the latest session update. Consistency across tools prevents context drift.
• Security hygiene: Run security-auditor.md before promoting to staging and paste the output into your ticket for audit trails.

Integrations & supporting toolchain

• Version control: git, gh, or lazygit for staging patches that Claude recommends.
• Package managers: npm/pnpm, pip, poetry, bundler, composer—Claude can draft upgrade plans, you execute the command, and it validates logs.
• Testing frameworks: pytest, jest, vitest, rspec. Ask Claude to suggest focused test commands and summarise failures.
• Observability: For backend or ops work, feed logs from Grafana, Datadog, or CloudWatch directly into Claude for root-cause brainstorming.
• Knowledge bases: Link outputs back to Notion/Confluence by using session-closer.md to produce tidy status summaries.

Golden rules for Claude

• Never run /project:session-update without pasting tangible evidence (diff, command output, decision summary).
• Pin guardrail agents (reliability-commander, testing-expert, session-closer) so you close every loop with a checklist.
• Use /tool run for deterministic outputs when you need reproducibility for audits.
• Archive every session log before rotating to a new initiative—file the markdown inside your long-term session history for easy searchability.