Skip to content

README.md

Latest commit

 

History

History
256 lines (187 loc) · 10.2 KB

README.md

File metadata and controls

256 lines (187 loc) · 10.2 KB

Claude Code Python Showcase

Production-ready Claude Code infrastructure for Python projects — specialist agents, curated skills, slash commands, and personal config management.

What This Repo Is

Two things in one:

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

Repo Structure

claude-code-python-showcase/
│
├── .claude/                    ← Personal config (mirrors ~/.claude/)
│   ├── agents/                 10 specialist agents
│   ├── commands/               9 slash commands (pr, plan, tdd, code-review, etc.)
│   ├── skills/                 12 curated skills (python-patterns, postgres, docker, etc.)
│   ├── hooks/                  4 shell hook scripts (block-dangerous-bash, protect-files, etc.)
│   ├── scripts/
│   │   ├── hooks/              5 JS hook scripts (session-start, session-end, etc.)
│   │   ├── lib/                4 JS utility modules (session-manager, utils, etc.)
│   │   └── pg-mcp.sh          PostgreSQL MCP bridge
│   ├── rules/
│   │   ├── common/             8 global coding rules
│   │   └── python/             5 Python-specific rules
│   ├── mcp/                    MCP server configs + hooks config
│   ├── settings.json           Project Claude settings
│   └── install.sh              ← Install personal config to ~/.claude/
│
├── setup_target_project.py     ← Install infrastructure into a target project
├── compile_rules.py            ← Compile skill-rules.json → CLAUDE.md
├── agents_generator.py         Copies agents from .claude/agents/
├── commands_generator.py       Copies commands from .claude/commands/
├── hooks_generator.py          Copies hooks + JS scripts from .claude/
├── skills_generator.py         Copies skills from .claude/skills/ + generates skill-rules.json
├── examples_generator.py       Example implementation templates
├── update_component.sh         Update components in an existing installation
└── dev/active/                 Active feature context (CONTEXT.md, TASK.md, PLAN.md)

Use Case 1: Install Personal Config on a New Machine

git clone <repo>
./.claude/install.sh --all          # install everything to ~/.claude/
./.claude/install.sh --mcp          # show MCP + hooks wiring instructions

Individual components:

./.claude/install.sh --agents
./.claude/install.sh --skills
./.claude/install.sh --hooks
./.claude/install.sh --rules

Sync local changes back to the repo:

./.claude/install.sh --sync         # copies ~/.claude/ → repo .claude/
git diff .claude/                   # review
git add .claude/ && git commit

How the personal config works

The personal config uses agents + commands + skills as standalone components — no automatic routing. You invoke them explicitly:

  • Slash commands (/plan, /tdd, /code-review, etc.) — trigger predefined workflows
  • Agent dispatch (Use planner agent..., Use tdd-guide...) — invoke specialists by name
  • /orchestrate — chains agents in a fixed pipeline (e.g., planner → tdd-guide → code-reviewer → security-reviewer)
  • Skills — knowledge libraries loaded by agents on demand, not auto-routed

Use Case 2: Install Infrastructure Into a Target Project

python setup_target_project.py --target /path/to/your/project --all

This copies the same .claude/ infrastructure from the showcase into your target project:

Component What gets installed
Skills (12) python-patterns, async-python-patterns, python-testing, tdd-workflow, postgres-patterns, docker-patterns, deployment-patterns, security-review, design-doc-mermaid, perplexity-deep-search, verification-loop, strategic-compact
Agents (10) planner, architect, tdd-guide, code-reviewer, security-reviewer, fastapi-specialist, aws-specialist, k8s-specialist, python-database-expert, python-debugger
Commands (9) /pr, /plan, /tdd, /code-review, /build-fix, /test-coverage, /verify, /update-docs, /orchestrate
Hooks 4 shell hooks + 5 JS hooks + 4 JS library modules
Rules (13) 8 common + 5 Python-specific coding rules

Then compile skill routing rules into CLAUDE.md:

python compile_rules.py --target /path/to/your/project

Or 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

3-Layer Skill Routing (target projects only)

When installed into a target project via setup_target_project.py, the generator creates a skill-rules.json routing table that enables automatic skill activation based on intent — not manual invocation.

Layer 1 — CLAUDE.md (native, always loaded)
  compile_rules.py reads skill-rules.json and writes routing instructions
  into CLAUDE.md. Claude reads this natively every session.

Layer 2 — SessionStart hook (injected at session start)
  session-start.js reads skill-rules.json + dev/active/*.md and injects
  the routing table + project context into every session automatically.

Layer 3 — /orchestrate command (explicit routing)
  Chains agents in a pipeline: planner → tdd-guide → code-reviewer →
  security-reviewer, loading relevant skills at each step.

Routing table (generated from skill-rules.json):

Intent keywords Skill loaded Agent invoked
python, framework, type hints python-patterns architect
async, await, asyncio async-python-patterns fastapi-specialist
pytest, test, coverage python-testing tdd-guide
tdd, test first tdd-workflow tdd-guide
postgres, sql, schema postgres-patterns python-database-expert
docker, container docker-patterns k8s-specialist
deploy, ci/cd, health check deployment-patterns k8s-specialist
security, auth, vulnerability security-review security-reviewer
mermaid, diagram design-doc-mermaid architect
search, research perplexity-deep-search planner
verify, validate verification-loop code-reviewer

Note: The personal config (Use Case 1) does not include skill-rules.json or automatic routing. It uses explicit agent invocation and slash commands instead.

Personal Config: What's Included

Agents (10)

Core workflow: planner, architect, code-reviewer, security-reviewer, tdd-guide

Stack-specific: fastapi-specialist, aws-specialist, k8s-specialist

Database: python-database-expert

Debugging: python-debugger

Commands (9)

Command Purpose
/pr Create GitHub pull request
/plan Restate requirements, assess risks, create implementation plan
/tdd Enforce test-driven development workflow
/code-review Run code review on changed files
/build-fix Build project and fix errors
/test-coverage Analyze and report test coverage
/verify Run verification checks
/update-docs Update documentation
/orchestrate Orchestrate multi-agent workflows

Skills (12)

Python: python-patterns, async-python-patterns, python-testing, tdd-workflow

Infrastructure: postgres-patterns, docker-patterns, deployment-patterns

Security: security-review

Diagramming: design-doc-mermaid

AI/Web search: perplexity-deep-search

Workflow: verification-loop, strategic-compact

Rules (13)

Common (8): coding-style, git-workflow, testing, security, performance, patterns, agents, hooks

Python (5): coding-style, hooks, patterns, security, testing

Hooks — Shell Scripts (4)

Hook Event Purpose
block-dangerous-bash.sh PreToolUse (Bash) Blocks rm -rf /, curl|bash
protect-files.sh PreToolUse (Edit/Write) Blocks .env, *.pem edits
session-context.sh SessionStart Re-injects project context
validate-sql.py PreToolUse (MCP postgres) Validates SQL before execution

Hooks — JS Scripts (5)

Script Purpose
session-start.js Load previous session context and learned skills
session-end.js Cleanup and session summary
evaluate-session.js Post-session evaluation
pre-compact.js Save state before context compaction
suggest-compact.js Suggest compaction at logical boundaries

JS Utility Libraries (4)

Module Purpose
package-manager.js Package manager detection and operations
session-aliases.js Session alias management
session-manager.js Session lifecycle management
utils.js Common utilities

MCP Servers

Name Purpose
cmem Session memory + lesson tracking
atlassian Jira + Confluence (SSE)
mermaid Mermaid diagram live preview
postgres-customer Customer DB read-only access
postgres-processing Processing DB read-only access

Key Design Principles

Skills as knowledge libraries — SKILL.md files contain patterns, checklists, and code templates. They don't execute; agents load and apply them.

Agents as domain experts — Each agent has explicit activation patterns and a mandatory first step: load its domain skill before any analysis.

.claude/ = source of truth — Generators copy files from the .claude/ directory instead of embedding content as Python strings. Edit .claude/ files directly; generators just copy them.

500-line rule — SKILL.md stays under 500 lines. Detailed content lives in resources/*.md, loaded on demand to avoid context explosion.

Docs

Doc Contents
docs/workflow.md PRD to implementation — who does what, why it's not fully autonomous, how to increase autonomy

License

MIT