Templates -- Starter Files for Claude Code

Copy these templates into your project to get started quickly. Both files are designed to be customized for your specific stack and workflow.

CLAUDE.md Template

The CLAUDE.md file is loaded into every Claude Code conversation. It tells Claude your project's stack, coding standards, module boundaries, and verification commands.

Copy to: your-project/CLAUDE.md

# [Project Name] — Claude Development Rules

## Quick Context

- **Stack**: [e.g., Python 3.12 + FastAPI + PostgreSQL]
- **Run**: `[command to start dev server]`
- **Test**: `[command to run tests]`
- **Build**: `[command to build]`
- **Lint**: `[command to lint]`

---

## Coding Standards

### Import Order
```
1. Standard library
2. Third-party packages
3. Framework imports
4. Relative/local imports
```

### Naming Conventions
- Files: `snake_case.py` / `kebab-case.ts`
- Classes: `PascalCase`
- Functions/methods: `snake_case` / `camelCase`
- Constants: `UPPER_SNAKE_CASE`

### Error Handling
- Use framework-specific exceptions (not generic `Exception`)
- Always handle external I/O with try/except
- Log errors with context: `logger.error('Failed to process %s: %s', item_id, str(e))`

---

## Module Boundaries

| Domain | Directories | Notes |
|--------|------------|-------|
| **Core** | `src/core/` | Shared utilities, base classes |
| **API** | `src/api/` | Route handlers, middleware |
| **Models** | `src/models/` | Database models, schemas |
| **Services** | `src/services/` | Business logic |

**Shared files (coordinate before editing):**
- `src/core/config.py` — used by all modules
- `docker-compose.yaml` — affects all services

---

## Verification

After making changes, verify:

```bash
# Run tests
[test command]

# Lint
[lint command]

# Build
[build command]

# Type check (if applicable)
[type check command]
```

---

## Common Patterns

### [Pattern 1 Name]
```python
# Describe the preferred pattern for common operations
```

### [Pattern 2 Name]
```python
# Another common pattern
```

---

## Common Mistakes to Avoid

1. **[Mistake]**: [Description and correct approach]
2. **[Mistake]**: [Description and correct approach]

---

## Getting Help

When asking for help:
1. Reference the specific file and function
2. Provide business context
3. Show what you've tried

---

settings-local.json Template

The settings.local.json file configures pre-approved commands and hooks. It is gitignored (personal to each developer).

Copy to: your-project/.claude/settings.local.json

{
  "permissions": {
    "allow": [
      "// --- Git (read-only) ---",
      "Bash(git status*)",
      "Bash(git diff*)",
      "Bash(git log*)",
      "Bash(git branch*)",
      "Bash(git show*)",
      "Bash(git stash list*)",

      "// --- Git (write) ---",
      "Bash(git add*)",
      "Bash(git commit*)",
      "Bash(git checkout*)",
      "Bash(git switch*)",
      "Bash(git merge*)",
      "Bash(git rebase*)",
      "Bash(git stash*)",
      "Bash(git push*)",

      "// --- GitHub CLI ---",
      "Bash(gh pr*)",
      "Bash(gh issue*)",
      "Bash(gh api*)",

      "// --- Package managers (uncomment yours) ---",
      "// Bash(npm *)",
      "// Bash(npx *)",
      "// Bash(yarn *)",
      "// Bash(pnpm *)",
      "// Bash(pip *)",
      "// Bash(pip3 *)",
      "// Bash(poetry *)",
      "// Bash(cargo *)",
      "// Bash(go *)",

      "// --- Build & test (uncomment yours) ---",
      "// Bash(make *)",
      "// Bash(pytest *)",
      "// Bash(python3 -m pytest*)",
      "// Bash(npm test*)",
      "// Bash(npm run *)",

      "// --- Docker (uncomment if needed) ---",
      "// Bash(docker compose *)",
      "// Bash(docker exec *)",
      "// Bash(docker ps*)",
      "// Bash(docker logs*)",

      "// --- Safe utilities ---",
      "Bash(ls *)",
      "Bash(wc *)",
      "Bash(mkdir *)",
      "Bash(cp *)",
      "Bash(mv *)"
    ],
    "deny": []
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "python3 .claude/hooks/security-check.py"
          }
        ]
      }
    ]
  }
}

How to Customize

1. Uncomment the package manager and build/test commands for your stack
2. Add project-specific commands you want pre-approved
3. Add additional hooks (see Hooks for available scripts)
4. Remove any commands you prefer to review manually