Mike Swanson
fb56de5b69
Added comprehensive section on PowerShell execution patterns: - Documented mandatory -NoProfile -File approach - Explained rationale (prevents font/codepage changes, avoids Git Bash quoting issues) - Referenced .claude/hooks/pre-bash-pwsh-script.sh enforcement - Provided correct and incorrect examples This addresses recurring font change issues on Windows when running PowerShell commands through Claude Code CLI. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
108 lines
2.9 KiB
Markdown
108 lines
2.9 KiB
Markdown
# 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
|