Claude Code Python Template

A repo built on this template, heading to Mars.

A reusable .claude/ configuration template for Claude Code Python projects. It enables fast, accurate prototyping and establishes a self-improvement loop grounded in documentation and evidence.

Core Features

🔄 Bidirectional template sync — Keep downstream projects and this template in sync. When a downstream project discovers a useful pattern, it can propose changes upstream; the template consolidates and broadcasts updates back to all projects.

📝 Documentation-driven self-improvement loop — Every stage of development — planning, implementation, review, and retrospective — produces structured documents (ADRs, lessons-learned, trade-off analyses). These documents serve as the shared memory that lets both the human and the AI agent improve their own workflow over time: revisiting past decisions, correcting recurring mistakes, and refining the process itself based on evidence rather than intuition.

💡 Creative and analytical thinking skills — Beyond code generation, the template ships skills that reframe hard problems through structured thinking frameworks: rethink-unblock breaks circular reasoning with targeted reframing, davinci-define applies the seven Da Vincian principles to clarify goals and life choices, and sparks-create uses the 13 tools from Sparks of Genius to generate cross-disciplinary creative angles. Use these when conventional analysis stalls.

🛡️ Python quality pipeline — A pre-commit pipeline enforces Python conventions on every commit: ruff for linting and formatting, bandit for security scanning, and pip-audit for dependency vulnerability checks. The check skill runs all gates in read-only mode for inspection; auto-fix applies safe automated fixes.

This workflow originated from citypaul/.dotfiles. For details, see Workflow: Plan-Implement-Document-Guard and Template Management Skill.

External Services

This template includes optional integrations with third-party services. Some have commercial pricing:

Service	Purpose	Free tier	Pricing
jcodemunch	Code navigation & symbol search via MCP	—	Paid for commercial use

If you don't need jcodemunch, remove mcp__jcodemunch entries from .mcp.json and .claude/rules/code-navigation-guidelines.md.

Getting Started

1. Clone this repository.

   git clone https://github.com/tae0y/python-project-template.git my-project
   cd my-project

2. Run the initialization script.

   bash scripts/init-project.sh my-project

   This removes template-only directories (localdocs/, proposals/, resources/, *.nouse/), deletes .gitkeep files, updates pyproject.toml and README.md with the project name, and bootstraps a fresh localdocs/ directory.

3. Set up the Python environment.

   uv sync

4. Install the pre-commit hook.

   pre-commit install --hook-type commit-msg

5. Customize CLAUDE.md for your project. See CLAUDE.sample.md for reference.

   Note: If you use a shared TIL repository, move .claude/skills.nouse/localdocs-til-link into .claude/skills/ and run /localdocs-til-link to symlink localdocs/ there.

6. The full directory structure looks like this:

   .claude/
   ├── WORKFLOW.md              # Workflow trigger map
   ├── settings.json            # Global settings
   ├── rules/                   # Behavioral rules applied to every response
   ├── commands/                # Reusable prompt templates
   ├── hooks/                   # Lifecycle shell scripts (pre-commit gate, convention checks)
   ├── skills/                  # Domain-specific capability definitions
   │   ├── tdd/                 # TDD workflow
   │   ├── planning/            # Task breakdown into known-good increments
   │   ├── check/               # Code quality inspection (ruff, pyright, bandit)
   │   ├── auto-fix/            # Lint & format auto-fix
   │   ├── rethink-unblock/     # Reframe stuck problems
   │   ├── davinci-define/      # Da Vincian principles for goal clarity
   │   ├── sparks-create/       # Cross-disciplinary creative thinking
   │   ├── template-broadcast/  # Batch rollout to all downstream projects
   │   └── ...
   ├── skills.nouse/            # Disabled skills (preserved for re-activation)
   └── agents/                  # Specialized sub-agent definitions