Skip to content

CLAUDE.md

Latest commit

 

History

History
360 lines (267 loc) · 13.6 KB

CLAUDE.md

File metadata and controls

360 lines (267 loc) · 13.6 KB
Raw

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What This Repo Is

A dual-purpose repository:

  1. Personal config store — .claude/ mirrors ~/.claude/, version-controlled and installable on any machine via .claude/install.sh
  2. Generator system — Python scripts that install Claude Code infrastructure (agents, skills, commands, hooks, rules) into any target Python/FastAPI project

Key Commands

Personal Config (Use Case 1)

# Install everything to ~/.claude/
./.claude/install.sh --all

# Install individual components
./.claude/install.sh --agents
./.claude/install.sh --skills
./.claude/install.sh --hooks
./.claude/install.sh --rules
./.claude/install.sh --mcp          # prints MCP wiring instructions

# Sync local ~/.claude/ changes back to this repo
./.claude/install.sh --sync
./.claude/install.sh --dry-run      # preview without writing

Target Project Installation (Use Case 2)

# Install all components into a target project
python setup_target_project.py --target /path/to/project --all
python setup_target_project.py --target /path/to/project --all --non-interactive

# Install individual components
python setup_target_project.py --target /path/to/project --component skills
python setup_target_project.py --target /path/to/project --component agents
python setup_target_project.py --target /path/to/project --component rules
python setup_target_project.py --target /path/to/project --component hooks
python setup_target_project.py --target /path/to/project --component commands

# Compile skill routing rules into CLAUDE.md for a target project
python compile_rules.py --target /path/to/project
python compile_rules.py --target /path/to/project --dry-run   # preview output

# Update a single component in an existing installation
./update_component.sh /path/to/project skills
./update_component.sh /path/to/project all

Architecture

Source of Truth: .claude/

All installable content lives under .claude/. The generator scripts (agents_generator.py, skills_generator.py, etc.) copy files from .claude/ rather than embedding content as strings. To change what gets installed, edit the files in .claude/ directly.

.claude/
├── agents/          # 10 specialist agent .md files
├── commands/        # 9 slash command .md files
├── skills/          # 12 skill directories (each has SKILL.md + optional resources/)
│   └── skill-rules.json    # routing metadata (generated by skills_generator.py)
├── hooks/           # 4 shell/Python hook scripts
├── scripts/
│   ├── hooks/       # 5 JS hook scripts (session-start, session-end, etc.)
│   └── lib/         # 4 JS utility modules
├── rules/
│   ├── common/      # 8 common coding rules (auto-loaded by Claude)
│   └── python/      # 5 Python-specific rules
├── mcp/             # MCP server configs + hooks-config.json
├── settings.json
└── install.sh       # installs to ~/.claude/

Generator Scripts

Script Role
setup_target_project.py Orchestrator — runs all generators for a target project
agents_generator.py Copies .claude/agents/*.md to target
commands_generator.py Copies .claude/commands/*.md to target
skills_generator.py Copies .claude/skills/*/ + generates skill-rules.json
hooks_generator.py Copies .claude/hooks/ + .claude/scripts/ to target
compile_rules.py Reads skill-rules.json → writes skill routing table into target CLAUDE.md
examples_generator.py Creates example implementation files in target project
update_component.sh Bash wrapper for updating a single component in an existing installation

Skill Routing (Target Projects Only)

When installed into a target project, compile_rules.py generates a routing table in that project's CLAUDE.md. The routing is defined in skills_generator.py (SKILL_METADATA) and compile_rules.py (SKILL_AGENT_MAP). Three layers activate skills:

  1. CLAUDE.md — routing table compiled from skill-rules.json, loaded every session
  2. SessionStart hook — session-start.js re-injects routing + dev/active/*.md context
  3. /orchestrate command — explicit pipeline: planner → tdd-guide → code-reviewer → security-reviewer

The personal config (.claude/install.sh) does not include auto-routing — it uses explicit agent invocation.

Skill Structure

Each skill directory follows the pattern:

.claude/skills/<skill-name>/
├── SKILL.md          # main content (≤500 lines)
└── resources/        # optional: detailed docs loaded on demand

Agents load a skill by reading its SKILL.md before any analysis.

Key Design Constraints

  • 500-line cap on SKILL.md — detailed content belongs in resources/*.md, loaded on demand
  • skill-rules.json is generated — edit SKILL_METADATA in skills_generator.py, then re-run setup_target_project.py --component skills or compile_rules.py
  • Auto-generated CLAUDE.md section — compile_rules.py appends a marked block; re-running replaces it. Don't manually edit lines after `

Skill Routing Rules (Auto-Generated — do not edit manually)

When working on tasks, Claude MUST follow this routing table. Match the user's intent against the patterns below and load the corresponding skill BEFORE writing any code. Loading a skill means reading its SKILL.md and applying its patterns, checklists, and code templates.

Intent Skill to Load Specialist Agent
python, framework, type hints, project structure python-patterns architect
async, await, asyncio, concurrent async-python-patterns fastapi-specialist
pytest, test, fixture, mock python-testing tdd-guide
tdd, test first, red green, test driven tdd-workflow tdd-guide
postgres, sql, schema, index postgres-patterns python-database-expert
docker, container, dockerfile, compose docker-patterns k8s-specialist
deploy, ci/cd, health check, rollback deployment-patterns k8s-specialist
security, auth, vulnerability, owasp security-review security-reviewer
mermaid, diagram, architecture, sequence diagram design-doc-mermaid architect
search, research, perplexity, deep search perplexity-deep-search planner
verify, validate, check, verification verification-loop code-reviewer
compact, context, summarize strategic-compact —
create skill, build skill, encode workflow, skill architect skill-architect —
pr review, pull request, code review, review pr pr-review —

Detailed Pattern Matching

python-patterns

Python principles, framework selection, async patterns, type hints

Trigger patterns (regex on user message):

  • (python|pythonic).*?(pattern|best practice|architecture)
  • (project|code).*?structure
  • type.*?hint

Active when editing:

  • **/*.py

Action: Load .claude/skills/python-patterns/SKILL.md, then invoke architect agent

async-python-patterns

Asyncio, concurrent programming, async/await patterns

Trigger patterns (regex on user message):

  • (async|await|asyncio).*?(pattern|convert|optimize)
  • (blocking|sync).*?(to async|convert)
  • concurrent.*?(programming|task)

Active when editing:

  • **/*async*.py
  • **/*concurrent*.py

Action: Load .claude/skills/async-python-patterns/SKILL.md, then invoke fastapi-specialist agent

python-testing

Pytest, TDD, fixtures, mocking, parametrization, 80%+ coverage

Trigger patterns (regex on user message):

  • (test|testing).*?(python|pytest|coverage)
  • (fixture|mock|parametr).*?(test|setup)
  • coverage.*?(report|check|increase)

Active when editing:

  • **/tests/**/*.py
  • **/test_*.py
  • **/*_test.py

Action: Load .claude/skills/python-testing/SKILL.md, then invoke tdd-guide agent

tdd-workflow

Test-first development, RED-GREEN-IMPROVE cycle

Trigger patterns (regex on user message):

  • (tdd|test.driven).*?(develop|workflow|approach)
  • (write|create).*?test.*?first
  • red.*?green.*?refactor

Active when editing:

  • **/tests/**/*.py

Action: Load .claude/skills/tdd-workflow/SKILL.md, then invoke tdd-guide agent

postgres-patterns

PostgreSQL optimization, schema design, indexing

Trigger patterns (regex on user message):

  • (postgres|postgresql|sql).*?(optimize|schema|index)
  • (query|database).*?(performance|slow|optimize)
  • (schema|migration).*?design

Active when editing:

  • **/models/**/*.py
  • **/migrations/**/*.py
  • **/*schema*.py

Action: Load .claude/skills/postgres-patterns/SKILL.md, then invoke python-database-expert agent

docker-patterns

Docker, Docker Compose, container security, volumes

Trigger patterns (regex on user message):

  • (docker|container).*?(build|optimize|secure)
  • dockerfile.*?(create|review|optimize)
  • (compose|multi.container).*?setup

Active when editing:

  • **/Dockerfile*
  • **/docker-compose*.yml
  • **/.dockerignore

Action: Load .claude/skills/docker-patterns/SKILL.md, then invoke k8s-specialist agent

deployment-patterns

CI/CD, containerization, health checks, rollback strategies

Trigger patterns (regex on user message):

  • (deploy|deployment).*?(pattern|strategy|pipeline)
  • (ci|cd|cicd).*?(pipeline|workflow|setup)
  • (health.*?check|readiness|liveness)

Active when editing:

  • **/.github/workflows/*.yml
  • **/k8s/**/*.yaml
  • **/helm/**/*

Action: Load .claude/skills/deployment-patterns/SKILL.md, then invoke k8s-specialist agent

security-review

Auth, secrets, API endpoints, security audit patterns

Trigger patterns (regex on user message):

  • (security|secure).*?(review|audit|scan)
  • (auth|authentication|authorization).*?(implement|review)
  • (vulnerability|owasp|injection).*?(check|prevent)

Active when editing:

  • **/auth/**/*.py
  • **/security/**/*.py
  • **/middleware/**/*.py

Action: Load .claude/skills/security-review/SKILL.md, then invoke security-reviewer agent

design-doc-mermaid

Mermaid diagrams for architecture, sequence, deployment docs

Trigger patterns (regex on user message):

  • (mermaid|diagram).*?(create|generate|design)
  • (architecture|sequence|deployment).*?diagram
  • (design.*?doc|technical.*?doc).*?(create|generate)

Active when editing:

  • **/*.md
  • **/docs/**/*

Action: Load .claude/skills/design-doc-mermaid/SKILL.md, then invoke architect agent

perplexity-deep-search

Deep search via Perplexity API for research tasks

Trigger patterns (regex on user message):

  • (deep|thorough).*?search
  • (research|investigate).*?(topic|question)
  • perplexity.*?(search|api)

Action: Load .claude/skills/perplexity-deep-search/SKILL.md, then invoke planner agent

verification-loop

Comprehensive verification and validation system

Trigger patterns (regex on user message):

  • (verify|validate|check).*?(implementation|code|result)
  • verification.*?(loop|cycle|process)

Action: Load .claude/skills/verification-loop/SKILL.md, then invoke code-reviewer agent

strategic-compact

Manual context compaction at logical intervals

Trigger patterns (regex on user message):

  • (compact|compress).*?context
  • strategic.*?(compact|summary)

Action: Load .claude/skills/strategic-compact/SKILL.md

skill-architect

Build reusable Claude Code skills (SKILL.md files) from workflow descriptions

Trigger patterns (regex on user message):

  • (create|build|write|make).*?skill
  • encode.*?(workflow|process|task)
  • skill.*?(template|architect|framework)

Active when editing:

  • .claude/skills/**/*

Action: Load .claude/skills/skill-architect/SKILL.md

pr-review

Reviews a GitHub PR diff for correctness, security, Python best practices, and test coverage

Trigger patterns (regex on user message):

  • (review|check|analyze).*?(pr|pull.request)
  • pr.*?(review|feedback|comments)
  • (what.*?wrong|issues).*?(pr|pull.request)

Action: Load .claude/skills/pr-review/SKILL.md

Orchestrator Protocol

For any non-trivial task, use the /orchestrate command or:

  1. Read dev/active/CONTEXT.md to understand project state
  2. Read dev/active/TASK.md for current task definition
  3. Match intent to routing table above
  4. Load matched skill(s) first
  5. Invoke specialist agent if available
  6. Update dev/active/PLAN.md before writing code

Available Agents

Agent Purpose
planner Implementation planning for complex features
architect System design + API design decisions
tdd-guide Test-driven development workflow
code-reviewer Python code quality review
security-reviewer Security analysis and audit
fastapi-specialist FastAPI framework patterns
aws-specialist AWS services integration
k8s-specialist Kubernetes + container infrastructure
python-database-expert PostgreSQL + SQLAlchemy + Alembic
pipecat-expert Real-time voice/multimodal AI pipelines
twilio-expert Twilio Programmable Voice + Media Streams
vapi-expert Vapi webhook integration + call data
python-debugger Root cause analysis and debugging

Skill Loading Instructions

To load a skill, read .claude/skills/<skill-name>/SKILL.md and apply all patterns, checklists, and templates found there to the current task. If a resources/ directory exists, load referenced files on demand.