# 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

---

## 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-04-02