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 <noreply@anthropic.com>
This commit is contained in:
Hutson Cappelmann
50
.gitignore
vendored
Normal file
50
.gitignore
vendored
Normal file
@@ -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
|
||||||
629
CLAUDE.md
Normal file
629
CLAUDE.md
Normal file
@@ -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_<module_name>.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-<package>
|
||||||
|
# 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
|
||||||
|
```
|
||||||
70
README.md
Normal file
70
README.md
Normal file
@@ -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)
|
||||||
Reference in New Issue
Block a user