From f4ba64fe6ac1fc9872378fd05047fbd7ddd9372f Mon Sep 17 00:00:00 2001 From: Hutson Cappelmann Date: Tue, 20 Jan 2026 14:46:44 -0500 Subject: [PATCH] Initial template: Comprehensive CLAUDE.md for new projects Includes: - Spec-driven development workflow - Type safety requirements (Python/TypeScript) - Tool usage guidelines (Ref, Exa, code review) - MCP configuration and disabling guide - Background agent patterns with spec context - Homelab infrastructure reference - Pre-commit checklist - Error recovery patterns - Permission boundaries Co-Authored-By: Claude Opus 4.5 --- .gitignore | 50 +++++ CLAUDE.md | 629 +++++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 70 ++++++ 3 files changed, 749 insertions(+) create mode 100644 .gitignore create mode 100644 CLAUDE.md create mode 100644 README.md diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..98681c1 --- /dev/null +++ b/.gitignore @@ -0,0 +1,50 @@ +# Dependencies +node_modules/ +venv/ +.venv/ +__pycache__/ +*.pyc +.pytest_cache/ + +# Build outputs +dist/ +build/ +*.egg-info/ +.next/ +out/ + +# IDE +.idea/ +.vscode/ +*.swp +*.swo +.DS_Store + +# Environment +.env +.env.local +.env.*.local +*.local.json + +# Logs +*.log +logs/ + +# Coverage +coverage/ +.coverage +htmlcov/ + +# Type checking +.mypy_cache/ +.dmypy.json + +# Testing +.pytest_cache/ +.tox/ + +# Secrets (never commit) +*.pem +*.key +credentials.json +secrets.json diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..7bbe3b4 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,629 @@ +# [PROJECT_NAME] - Claude Code Guidelines + +> **Template Instructions**: Copy this file to new projects and customize the sections marked with `[CUSTOMIZE]`. Delete this blockquote after customizing. + +## Project Overview + +[CUSTOMIZE] Brief description of what this project does and its purpose. + +**Tech Stack**: [CUSTOMIZE] e.g., Python/FastAPI, TypeScript/React, etc. + +**Key Directories**: +- `src/` - Main source code +- `tests/` - Test files +- `docs/` - Documentation + +--- + +## Spec-Driven Development (Required) + +**All features and significant changes MUST follow spec-driven development.** + +### Workflow + +``` +1. /speckit.specify → Define requirements (what & why, no tech choices) +2. /speckit.plan → Specify technology and architecture +3. /speckit.tasks → Break plan into ordered, actionable tasks +4. /speckit.implement → Build features according to the plan +5. /speckit.clarify → Resolve ambiguities as they arise +``` + +### When to Use Spec-Kit + +| Scenario | Use Spec-Kit? | +|----------|---------------| +| New feature | Yes | +| Significant refactoring | Yes | +| Bug fixes | No | +| Config changes | No | +| Documentation only | No | + +### Background Agents MUST Reference Specs + +When spawning background agents for implementation work, **always include spec context**: + +```python +# CORRECT: Agent has spec context +Task( + subagent_type="general-purpose", + prompt=""" + Implement the user authentication module. + + SPEC CONTEXT (from specs/auth.md): + - Use JWT tokens with 24h expiry + - Store refresh tokens in httpOnly cookies + - Rate limit: 5 failed attempts per 15 minutes + + PLAN CONTEXT (from plans/auth-plan.md): + - Use FastAPI dependency injection for auth middleware + - Pydantic models for token validation + + Implementation requirements: + - Follow the spec exactly + - Run tests after implementation + - Ensure type safety with mypy --strict + """, + run_in_background=True +) + +# WRONG: Agent has no context about the plan +Task( + subagent_type="general-purpose", + prompt="Implement user authentication", # Too vague! + run_in_background=True +) +``` + +**Before spawning agents**, always: +1. Read the relevant spec file(s) +2. Read the current plan +3. Include key constraints in the agent prompt +4. Specify verification steps (tests, type checks) + +--- + +## Type Safety (Strict Enforcement) + +**Type safety is non-negotiable. All code must pass strict type checking.** + +### Python +```bash +# Required before every commit +mypy --strict src/ +``` + +- Complete type hints on ALL functions (params + return types) +- No `# type: ignore` without documented justification +- Use `TypedDict` for complex dictionaries +- Use `Literal` for string enums +- Money/prices: Always `Decimal`, never `float` + +### TypeScript +```bash +# Required before every commit +bun run tsc --noEmit +``` + +- Enable `strict: true` in tsconfig.json +- No `any` types - use `unknown` and narrow +- Explicit return types on all functions +- Use discriminated unions for complex state + +### Verification Commands +```bash +# [CUSTOMIZE] Add project-specific type check commands +mypy --strict src/ # Python +bun run tsc --noEmit # TypeScript +``` + +--- + +## Required Tool Usage + +### 1. Documentation Lookup (Priority Order) + +**ALWAYS check documentation before implementing unfamiliar APIs:** + +``` +1. Ref Tools (private docs) → Check first for internal/uploaded docs + mcp__Ref__ref_search_documentation(query="topic ref_src=private") + +2. Ref Tools (public docs) → Framework/library documentation + mcp__Ref__ref_search_documentation(query="FastAPI dependency injection") + +3. Exa Tools → Web search (last resort) + mcp__exa__web_search_exa(query="...") + mcp__exa__get_code_context_exa(query="...") # Best for code questions +``` + +**Never guess at API usage. Look it up.** + +### 2. Web Search (Use Exa, Not WebFetch) + +| Tool | Use Case | +|------|----------| +| `mcp__exa__web_search_exa` | General web search | +| `mcp__exa__get_code_context_exa` | Programming docs, APIs, libraries | +| `mcp__exa__crawling_exa` | Extract content from specific URLs | +| `mcp__exa__deep_researcher_start` | Complex research (multiple sources) | + +### 3. Code Review + +**Run after completing significant features:** +``` +/code-review:code-review +``` + +### 4. Git Commits + +**Use for all commits:** +``` +/commit-commands:commit +``` + +**For complete workflow (commit + push + PR):** +``` +/commit-commands:commit-push-pr +``` + +### 5. Frontend Design + +**When building UI components or pages:** +``` +/frontend-design:frontend-design +``` + +This skill produces high-quality, production-grade frontend interfaces. + +### 6. Background Agents + +**Use for parallel, independent work:** + +```python +# Launch multiple agents for independent tasks +Task(subagent_type="general-purpose", prompt="...", run_in_background=True) +Task(subagent_type="general-purpose", prompt="...", run_in_background=True) +``` + +**When to use background agents:** +- Building multiple independent modules +- Running tests across different areas +- Implementing features that don't depend on each other +- Parallel research tasks + +**Always include in agent prompts:** +- Spec/plan context (see above) +- Type safety requirements +- Verification steps + +--- + +## MCP Configuration + +### Active MCPs for This Project + +[CUSTOMIZE] List the MCPs this project actually needs: + +``` +# Example - keep only what's needed: +- exa (web search) +- Ref (documentation) +- ticktick (task management) - optional +- claude-in-chrome (browser automation) - only if needed +``` + +### Disabling Unused MCPs + +**Disable MCPs that aren't needed for this project to reduce noise and improve performance.** + +To disable MCPs project-wide, add to `.claude/settings.json`: + +```json +{ + "mcpServers": { + "unused-mcp-name": { + "disabled": true + } + } +} +``` + +Or use `/config` → MCP Servers → toggle off unused servers. + +### MCP Usage Guidelines + +| MCP | When to Use | When to Disable | +|-----|-------------|-----------------| +| `exa` | Web search, research | Never (always useful) | +| `Ref` | Documentation lookup | Never (always useful) | +| `ticktick` | Task management | Backend-only projects | +| `claude-in-chrome` | Browser automation, UI testing | Backend-only projects | +| `beeper` | Messaging integration | Most projects | +| `shopping` | E-commerce features | Non-commerce projects | + +--- + +## Pre-Commit Checklist + +Before every commit, verify: + +```bash +# 1. Type safety +mypy --strict src/ # Python +bun run tsc --noEmit # TypeScript + +# 2. Linting +ruff check src/ # Python +bun run lint # TypeScript + +# 3. Formatting +black src/ # Python +bun run format # TypeScript + +# 4. Tests +pytest # Python +bun test # TypeScript + +# 5. Code review (for significant changes) +/code-review:code-review +``` + +--- + +## Documentation Requirements + +### Keep Updated + +- **README.md**: Update when adding features, changing setup, or modifying APIs +- **CLAUDE.md**: Update when conventions change or new patterns emerge +- **Spec files**: Update when requirements change mid-implementation +- **API docs**: Update when endpoints change + +### When to Update CLAUDE.md + +Update this file when: +- Claude makes repeated mistakes → Add specific guidance +- New tools/patterns are adopted → Document them +- Conventions change → Update the rules +- New team members join → Ensure onboarding clarity + +--- + +## Code Quality Standards + +### General Rules + +- **No over-engineering**: Only implement what's requested +- **No premature abstraction**: Three similar lines > unnecessary helper +- **No unused code**: Delete completely, don't comment out +- **No backwards-compat hacks**: If unused, remove it + +### Security + +- Validate all external inputs +- Never log sensitive data (passwords, tokens, PII) +- Use parameterized queries (no SQL injection) +- Escape output (no XSS) + +### Error Handling + +- Handle errors at system boundaries +- Don't catch generic exceptions without re-raising +- Log errors with context +- Fail fast on invalid state + +--- + +## Project-Specific Patterns + +[CUSTOMIZE] Document patterns specific to this project: + +### API Conventions +```python +# Example: Standard response format +{ + "data": {...}, + "error": null, + "meta": {"timestamp": "..."} +} +``` + +### Naming Conventions +- Files: `snake_case.py` / `kebab-case.ts` +- Classes: `PascalCase` +- Functions: `snake_case` / `camelCase` +- Constants: `UPPER_SNAKE_CASE` + +### Testing Patterns +```python +# Example: Test file naming +tests/ + test_.py + conftest.py # Shared fixtures +``` + +--- + +## Quick Reference + +### Starting a New Feature +```bash +/speckit.specify # Define what you're building +/speckit.plan # Plan how to build it +/speckit.tasks # Break into tasks +/speckit.implement # Build it +/code-review:code-review +/commit-commands:commit +``` + +### Bug Fix (Skip Spec-Kit) +```bash +# Direct implementation +# Then: +/code-review:code-review +/commit-commands:commit +``` + +### Research Before Coding +``` +1. mcp__Ref__ref_search_documentation # Check docs first +2. mcp__exa__get_code_context_exa # Then web search +``` + +--- + +## Homelab Infrastructure (Available Resources) + +Reference documentation: `~/Projects/homelab/` + +### Servers + +| Server | IP | Specs | GPU | Purpose | +|--------|-----|-------|-----|---------| +| **PVE** | 10.10.10.120 | Threadripper PRO 3975WX (32C/64T), 128GB ECC | TITAN RTX (24GB) | Primary Proxmox host | +| **PVE2** | 10.10.10.102 | Threadripper PRO 3975WX (32C/64T), 128GB ECC | RTX A6000 (48GB) | Secondary Proxmox host | + +### Key VMs (for deployment targets) + +| VMID | Name | IP | Purpose | Resources | +|------|------|-----|---------|-----------| +| 100 | truenas | 10.10.10.200 | Central NAS, NFS/SMB | ZFS vault pool | +| 101 | saltbox | 10.10.10.100 | Media services (Plex, *arr) | TITAN RTX passthrough | +| 111 | lmdev1 | 10.10.10.111 | AI/LLM development | TITAN RTX (shared) | +| 206 | docker-host | 10.10.10.206 | Docker services | General purpose | +| 301 | trading-vm | 10.10.10.221 | AI trading platform | A6000 passthrough | + +### Services & URLs + +| Service | URL | Purpose | +|---------|-----|---------| +| Proxmox | https://pve.htsn.io:8006 | VM management | +| TrueNAS | https://truenas.htsn.io | Storage management | +| Gitea | https://git.htsn.io | Git repositories | +| Plex | https://plex.htsn.io | Media streaming | +| Home Assistant | https://homeassistant.htsn.io | Home automation | +| Traefik | 10.10.10.250:8080 | Reverse proxy dashboard | + +### Network + +- **LAN**: 10.10.10.0/24 (gateway: 10.10.10.1) +- **Internal storage**: 10.10.20.0/24 (no external access) +- **Tailscale**: 100.x.x.x overlay for remote access +- **10Gb**: Available between PVE, TrueNAS, Saltbox via vmbr1/vmbr2 + +### Storage Pools + +| Pool | Location | Capacity | Purpose | +|------|----------|----------|---------| +| nvme-mirror1 | PVE | 3.6 TB | Fast VM storage | +| nvme-mirror2 | PVE | 1.8 TB | Additional fast storage | +| rpool | PVE | 3.6 TB | Proxmox OS, containers | +| vault | TrueNAS | ~12+ TB | Central file storage | + +### SSH Access + +```bash +ssh pve # Primary Proxmox +ssh pve2 # Secondary Proxmox +ssh truenas # TrueNAS storage +ssh saltbox # Media services +ssh docker-host # Docker services +``` + +### Deployment Considerations + +- **AI/ML workloads**: Use lmdev1 (TITAN RTX) or trading-vm (A6000) +- **Docker services**: Deploy to docker-host (10.10.10.206) +- **Storage-heavy**: Use TrueNAS NFS mounts via 10.10.20.x network +- **Public services**: Route through Traefik at *.htsn.io + +--- + +## Gotchas & Anti-Patterns + +[CUSTOMIZE] Document things Claude should avoid or watch out for: + +### Known Gotchas + +- [CUSTOMIZE] e.g., "The `user.email` field can be null for OAuth users" +- [CUSTOMIZE] e.g., "Always use `get_db()` dependency, never create sessions directly" +- [CUSTOMIZE] e.g., "The legacy `/api/v1/` routes are deprecated, use `/api/v2/`" + +### Anti-Patterns (Do NOT Do These) + +- Don't use `setTimeout` for polling - use the existing `useInterval` hook +- Don't import from `@/lib/deprecated/*` - these are scheduled for removal +- Don't add new dependencies without checking `package.json` for existing alternatives + +### Known Tech Debt (Don't Copy These Patterns) + +[CUSTOMIZE] List files or patterns that exist but shouldn't be replicated: + +- `src/legacy/old_auth.py` - Legacy auth, use `src/auth/` instead +- `components/OldButton.tsx` - Use design system `Button` component +- Any file in `src/deprecated/` - These are migration targets + +--- + +## Permission Boundaries + +### Claude Should NOT Automatically: + +- Delete files or directories without explicit confirmation +- Push to `main` or `master` branches directly +- Modify `.env` files or secrets +- Run database migrations in production +- Make breaking API changes without discussion +- Install new major dependencies without asking + +### Always Ask Before: + +- Changing database schemas +- Modifying authentication/authorization logic +- Updating CI/CD configurations +- Changing public API contracts +- Removing features (even if they seem unused) + +--- + +## Environment-Specific Behavior + +### Development +```bash +# [CUSTOMIZE] Dev-specific commands +bun run dev # Start dev server +docker-compose up -d # Local services +``` + +### Testing +```bash +# [CUSTOMIZE] Test commands +pytest --cov=src # With coverage +bun test --watch # Watch mode +``` + +### Production (Read-Only Context) +- Never run destructive commands against production +- Use read-only database connections for debugging +- Always use staging for testing changes first + +--- + +## Domain Terminology + +[CUSTOMIZE] Define project-specific terms Claude should understand: + +| Term | Definition | +|------|------------| +| [CUSTOMIZE] | e.g., "Workspace" = A collection of projects belonging to one org | +| [CUSTOMIZE] | e.g., "Pipeline" = The CI/CD workflow, not data processing | +| [CUSTOMIZE] | e.g., "Agent" = Background worker process, not AI agent | + +--- + +## Hooks Configuration + +[CUSTOMIZE] Document any automated hooks in `.claude/settings.json`: + +### Recommended Hooks + +```json +{ + "hooks": { + "postToolUse": [ + { + "tool": "Edit", + "command": "bun run format --write $FILE" + } + ], + "preCommit": [ + { + "command": "bun run lint && bun run typecheck" + } + ] + } +} +``` + +### Active Hooks in This Project + +- [CUSTOMIZE] e.g., "Auto-format on file edit" +- [CUSTOMIZE] e.g., "Run tests on save" +- [CUSTOMIZE] e.g., "Block direct edits to main branch" + +--- + +## Modular Rules (For Large Projects) + +For complex projects, break rules into `.claude/rules/` directory: + +``` +.claude/ + rules/ + code-style.md # Formatting, naming conventions + testing.md # Test patterns and requirements + security.md # Security requirements + api-design.md # API conventions + frontend/ + components.md # Component patterns + state.md # State management rules + backend/ + database.md # DB access patterns + services.md # Service layer conventions +``` + +All `.md` files in `.claude/rules/` are automatically loaded. + +--- + +## Error Recovery + +### When Tests Fail + +1. Read the full error message +2. Check if it's a flaky test (run again) +3. Check recent changes that might have caused it +4. Fix the root cause, don't just make the test pass + +### When Type Checks Fail + +1. Don't add `# type: ignore` without understanding why +2. Check if types need updating in a shared module +3. Ensure third-party type stubs are installed +4. Document any legitimate type: ignore with a reason + +### When Stuck + +1. Re-read the spec/plan for context +2. Check Ref Tools for documentation +3. Search with Exa for solutions +4. Ask for clarification rather than guessing + +--- + +## Troubleshooting + +[CUSTOMIZE] Add project-specific troubleshooting: + +### Common Issues + +**Type errors with third-party libraries:** +```bash +# Install type stubs +pip install types- +# Or add to pyproject.toml py.typed packages +``` + +**Tests failing in CI but not locally:** +```bash +# Check for environment differences +# Ensure all deps are in requirements.txt/package.json +``` + +**MCP tools not working:** +```bash +# Check MCP server status +/config → MCP Servers → verify connection +# Restart Claude Code if needed +``` diff --git a/README.md b/README.md new file mode 100644 index 0000000..5488503 --- /dev/null +++ b/README.md @@ -0,0 +1,70 @@ +# Project Template + +Template repository for new projects with Claude Code integration. + +## Quick Start + +1. Clone this template: + ```bash + git clone git@git.htsn.io:hutson/template-project.git my-new-project + cd my-new-project + rm -rf .git && git init + ``` + +2. Customize `CLAUDE.md`: + - Update `[PROJECT_NAME]` with your project name + - Fill in `[CUSTOMIZE]` sections + - Remove template instructions blockquote + +3. Start development with spec-kit: + ```bash + /speckit.specify # Define requirements + /speckit.plan # Plan implementation + /speckit.tasks # Break into tasks + /speckit.implement # Build it + ``` + +## What's Included + +- `CLAUDE.md` - Comprehensive Claude Code configuration with: + - Spec-driven development workflow + - Type safety requirements (Python/TypeScript) + - Tool usage guidelines (Ref, Exa, code review, etc.) + - MCP configuration + - Background agent patterns + - Homelab infrastructure reference + - Pre-commit checklist + - Error recovery patterns + +## Directory Structure + +``` +. +├── CLAUDE.md # Claude Code instructions +├── README.md # This file +├── src/ # Source code (create as needed) +├── tests/ # Test files (create as needed) +├── docs/ # Documentation (create as needed) +└── specs/ # Spec-kit specifications (if using) +``` + +## Workflow + +### New Feature +``` +/speckit.specify → /speckit.plan → /speckit.tasks → /speckit.implement +/code-review:code-review +/commit-commands:commit +``` + +### Bug Fix +``` +# Direct implementation, then: +/code-review:code-review +/commit-commands:commit +``` + +## Related + +- [Homelab Documentation](https://git.htsn.io/hutson/homelab) +- [Claude Code Best Practices](https://www.anthropic.com/engineering/claude-code-best-practices)