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