# ClaudeTools - Coding Guidelines

Project-specific standards. Generic language conventions (PEP 8, etc.) are assumed knowledge.

---

## Character Encoding

### NO EMOJIS - EVER

Never use emojis in code, scripts, config files, log messages, or output strings.

**Rationale:** Causes PowerShell parsing errors, encoding issues, terminal rendering problems.

**Use instead:**
```
[OK] [SUCCESS] [INFO] [WARNING] [ERROR] [CRITICAL]
```

**Exception:** User-facing web UI with proper UTF-8 handling.

---

## Naming Conventions

- **Python:** snake_case functions, PascalCase classes, UPPER_SNAKE constants
- **PowerShell:** PascalCase variables ($TaskName), approved verbs (Get-/Set-/New-)
- **Bash:** lowercase_underscore functions, quote all variables
- **DB tables:** lowercase plural (users, user_sessions), FK as {table}_id
- **DB columns:** created_at/updated_at timestamps, is_/has_ boolean prefixes

---

## PowerShell Execution (Windows)

### ALWAYS Use -NoProfile -File Pattern

Never use inline PowerShell commands (`-Command` or `-c`). Always write scripts to `.ps1` files and execute with `-NoProfile -File`.

**Rationale:**
- **Prevents font/codepage changes**: PowerShell profile scripts often set `chcp 65001` or modify `[Console]::OutputEncoding`, which changes the Claude Code CLI font and breaks rendering
- **Avoids Git Bash quoting issues**: Inline commands have unpredictable quote escaping and variable expansion (`$_`, `$foo`) before PowerShell sees them
- **Enforced by hooks**: `.claude/hooks/pre-bash-pwsh-script.sh` blocks inline execution and requires the file-based approach

**Correct:**
```bash
# Write script to file using Write tool
cat > /tmp/script.ps1 << 'EOF'
Get-Process | Select-Object -First 5 Name, CPU
EOF

# Execute with -NoProfile -File
pwsh -NoProfile -File /tmp/script.ps1
```

**Incorrect (BLOCKED BY HOOKS):**
```bash
# These will be rejected
powershell -Command "Get-Process"
pwsh -c "Get-Date"
powershell.exe -Command '$x = 5; Write-Host $x'
```

**Reference:** See `.claude/hooks/pre-bash-pwsh-script.sh` for enforcement details.

---

## Security

- Never hardcode credentials -- use SOPS vault or environment variables
- JWT tokens for API auth, Argon2 for password hashing
- Log all authentication attempts and sensitive operations
- `.env` files are gitignored, never committed

---

## API Standards

- RESTful with plural nouns: `/api/users`
- Consistent error format: `{"detail": "...", "error_code": "...", "status_code": N}`
- Paginate large result sets
- Document with OpenAPI (automatic with FastAPI)

---

## Output Markers

All scripts and tools use ASCII status markers:
```
[INFO] Starting process
[SUCCESS] Task completed
[WARNING] Configuration missing
[ERROR] Failed to connect
[CRITICAL] Database unavailable
```

---

## Git

- Commit types: feat, fix, refactor, docs, test, config
- Always include `Co-Authored-By` line for Claude commits
- Never commit .env, credentials, venv, __pycache__, *.log

---

**Last Updated:** 2026-05-12