diff --git a/.claude/CODING_GUIDELINES.md b/.claude/CODING_GUIDELINES.md index 6525cb5..62411b2 100644 --- a/.claude/CODING_GUIDELINES.md +++ b/.claude/CODING_GUIDELINES.md @@ -31,6 +31,40 @@ Never use emojis in code, scripts, config files, log messages, or output strings --- +## 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 @@ -70,4 +104,4 @@ All scripts and tools use ASCII status markers: --- -**Last Updated:** 2026-04-02 +**Last Updated:** 2026-05-12