claudetools/.claude/CODING_GUIDELINES.md

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:

# 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):

# 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