|
| 1 | +# Global Development Standards |
| 2 | + |
| 3 | +Global instructions for all projects. Project-specific CLAUDE.md files override these defaults. |
| 4 | + |
| 5 | +- Prefer Exa AI (`mcp__exa__web_search_exa`) over `WebSearch` for all web searches |
| 6 | +- Use skills proactively when they match the task — suggest relevant ones, don't block on them |
| 7 | + |
| 8 | +## Philosophy |
| 9 | + |
| 10 | +- **No speculative features** - Don't add features, flags, or configuration unless users actively need them |
| 11 | +- **No premature abstraction** - Don't create utilities until you've written the same code three times |
| 12 | +- **Clarity over cleverness** - Prefer explicit, readable code over dense one-liners |
| 13 | +- **Justify new dependencies** - Each dependency is attack surface and maintenance burden |
| 14 | +- **No phantom features** - Don't document or validate features that aren't implemented |
| 15 | +- **Replace, don't deprecate** - When a new implementation replaces an old one, remove the old one entirely. No backward-compatible shims, dual config formats, or migration paths. Proactively flag dead code — it adds maintenance burden and misleads both developers and LLMs. |
| 16 | +- **Verify at every level** - Set up automated guardrails (linters, type checkers, pre-commit hooks, tests) as the first step, not an afterthought. Prefer structure-aware tools (ast-grep, LSPs, compilers) over text pattern matching. Review your own output critically. Every layer catches what the others miss. |
| 17 | +- **Bias toward action** - Decide and move for anything easily reversed; state your assumption so the reasoning is visible. Ask before committing to interfaces, data models, architecture, or destructive/write operations on external services. |
| 18 | +- **Finish the job** - Don't stop at the minimum that technically satisfies the request. Handle the edge cases you can see. Clean up what you touched. If something is broken adjacent to your change, flag it. But don't invent new scope — there's a difference between thoroughness and gold-plating. |
| 19 | +- **Agent-native by default** - Design so agents can achieve any outcome users can. Tools are atomic primitives; features are outcomes described in prompts. Prefer file-based state for transparency and portability. When adding UI capability, ask: can an agent achieve this outcome too? |
| 20 | + |
| 21 | +## Code Quality |
| 22 | + |
| 23 | +### Hard limits |
| 24 | + |
| 25 | +1. ≤100 lines/function, cyclomatic complexity ≤8 |
| 26 | +2. ≤5 positional params |
| 27 | +3. 100-char line length |
| 28 | +4. Absolute imports only — no relative (`..`) paths |
| 29 | +5. Google-style docstrings on non-trivial public APIs |
| 30 | + |
| 31 | +### Zero warnings policy |
| 32 | + |
| 33 | +Fix every warning from every tool — linters, type checkers, compilers, tests. If a warning truly can't be fixed, add an inline ignore with a justification comment. Never leave warnings unaddressed; a clean output is the baseline, not the goal. |
| 34 | + |
| 35 | +### Comments |
| 36 | + |
| 37 | +Code should be self-documenting. No commented-out code—delete it. If you need a comment to explain WHAT the code does, refactor the code instead. |
| 38 | + |
| 39 | +### Error handling |
| 40 | + |
| 41 | +- Fail fast with clear, actionable messages |
| 42 | +- Never swallow exceptions silently |
| 43 | +- Include context (what operation, what input, suggested fix) |
| 44 | + |
| 45 | +### Reviewing code |
| 46 | + |
| 47 | +Evaluate in order: architecture → code quality → tests → performance. Before reviewing, sync to latest remote (`git fetch origin`). |
| 48 | + |
| 49 | +For each issue: describe concretely with file:line references, present options with tradeoffs when the fix isn't obvious, recommend one, and ask before proceeding. |
| 50 | + |
| 51 | +### Testing |
| 52 | + |
| 53 | +**Test behavior, not implementation.** Tests should verify what code does, not how. If a refactor breaks your tests but not your code, the tests were wrong. |
| 54 | + |
| 55 | +**Test edges and errors, not just the happy path.** Empty inputs, boundaries, malformed data, missing files, network failures — bugs live in edges. Every error path the code handles should have a test that triggers it. |
| 56 | + |
| 57 | +**Mock boundaries, not logic.** Only mock things that are slow (network, filesystem), non-deterministic (time, randomness), or external services you don't control. |
| 58 | + |
| 59 | +**Verify tests catch failures.** Break the code, confirm the test fails, then fix. Use mutation testing (`cargo-mutants`, `mutmut`) to verify systematically. Use property-based testing (`proptest`, `hypothesis`) for parsers, serialization, and algorithms. |
| 60 | + |
| 61 | +## Development |
| 62 | + |
| 63 | +When adding dependencies, CI actions, or tool versions, always look up the current stable version — never assume from memory unless the user provides one. |
| 64 | + |
| 65 | +### CLI tools |
| 66 | + |
| 67 | +| tool | replaces | usage | |
| 68 | +|------|----------|-------| |
| 69 | +| `rg` (ripgrep) | grep | `rg "pattern"` - 10x faster regex search | |
| 70 | +| `fd` | find | `fd "*.py"` - fast file finder | |
| 71 | +| `ast-grep` | - | `ast-grep --pattern '$FUNC($$$)' --lang py` - AST-based code search | |
| 72 | +| `shellcheck` | - | `shellcheck script.sh` - shell script linter | |
| 73 | +| `shfmt` | - | `shfmt -i 2 -w script.sh` - shell formatter | |
| 74 | +| `actionlint` | - | `actionlint .github/workflows/` - GitHub Actions linter | |
| 75 | +| `zizmor` | - | `zizmor .github/workflows/` - Actions security audit | |
| 76 | +| `prek` | pre-commit | `prek run` - fast git hooks (Rust, no Python) | |
| 77 | +| `wt` | git worktree | `wt switch branch` - manage parallel worktrees | |
| 78 | +| `trash` | rm | `trash file` - moves to macOS Trash (recoverable). **Never use `rm -rf`** | |
| 79 | + |
| 80 | +Prefer `ast-grep` over ripgrep when searching for code structure (function calls, class definitions, imports, pattern matching across arguments). Use ripgrep for literal strings and log messages. |
| 81 | + |
| 82 | +### Python |
| 83 | + |
| 84 | +**Runtime:** 3.13 with `uv venv` |
| 85 | + |
| 86 | +| purpose | tool | |
| 87 | +|---------|------| |
| 88 | +| deps & venv | `uv` | |
| 89 | +| lint & format | `ruff check` · `ruff format` | |
| 90 | +| static types | `ty check` | |
| 91 | +| tests | `pytest -q` | |
| 92 | + |
| 93 | +**Always use uv, ruff, and ty** over pip/poetry, black/pylint/flake8, and mypy/pyright — they're faster and stricter. Configure `ty` strictness via `[tool.ty.rules]` in pyproject.toml. Use `uv_build` for pure Python, `hatchling` for extensions. |
| 94 | + |
| 95 | +Tests in `tests/` directory mirroring package structure. Supply chain: `pip-audit` before deploying, pin exact versions (`==` not `>=`), verify hashes with `uv pip install --require-hashes`. |
| 96 | + |
| 97 | +### Node/TypeScript |
| 98 | + |
| 99 | +**Runtime:** Node 22 LTS, ESM only (`"type": "module"`) |
| 100 | + |
| 101 | +| purpose | tool | |
| 102 | +|---------|------| |
| 103 | +| lint | `oxlint` | |
| 104 | +| format | `oxfmt` | |
| 105 | +| test | `vitest` | |
| 106 | +| types | `tsc --noEmit` | |
| 107 | + |
| 108 | +**Always use oxlint and oxfmt** over eslint/prettier — they're faster and stricter. Enable `typescript`, `import`, `unicorn` plugins. |
| 109 | + |
| 110 | +**tsconfig.json strictness** — enable all of these: |
| 111 | +```jsonc |
| 112 | +"strict": true, |
| 113 | +"noUncheckedIndexedAccess": true, |
| 114 | +"exactOptionalPropertyTypes": true, |
| 115 | +"noImplicitOverride": true, |
| 116 | +"noPropertyAccessFromIndexSignature": true, |
| 117 | +"verbatimModuleSyntax": true, |
| 118 | +"isolatedModules": true |
| 119 | +``` |
| 120 | + |
| 121 | +Colocated `*.test.ts` files. Supply chain: `pnpm audit --audit-level=moderate` before installing, pin exact versions (no `^` or `~`), enforce 24-hour publish delay (`pnpm config set minimumReleaseAge 1440`), block postinstall scripts (`pnpm config set ignore-scripts true`). |
| 122 | + |
| 123 | +### Rust |
| 124 | + |
| 125 | +**Runtime:** Latest stable via `rustup` |
| 126 | + |
| 127 | +| purpose | tool | |
| 128 | +|---------|------| |
| 129 | +| build & deps | `cargo` | |
| 130 | +| lint | `cargo clippy --all-targets --all-features -- -D warnings` | |
| 131 | +| format | `cargo fmt` | |
| 132 | +| test | `cargo test` | |
| 133 | +| supply chain | `cargo deny check` (advisories, licenses, bans) | |
| 134 | +| safety check | `cargo careful test` (stdlib debug assertions + UB checks) | |
| 135 | + |
| 136 | +**Style:** |
| 137 | +- Prefer `for` loops with mutable accumulators over iterator chains |
| 138 | +- Shadow variables through transformations (no `raw_x`/`parsed_x` prefixes) |
| 139 | +- No wildcard matches; avoid `matches!` macro—explicit destructuring catches field changes |
| 140 | +- Use `let...else` for early returns; keep happy path unindented |
| 141 | + |
| 142 | +**Type design:** |
| 143 | +- Newtypes over primitives (`UserId(u64)` not `u64`) |
| 144 | +- Enums for state machines, not boolean flags |
| 145 | +- `thiserror` for libraries, `anyhow` for applications |
| 146 | +- `tracing` for logging (`error!`/`warn!`/`info!`/`debug!`), not println |
| 147 | + |
| 148 | +**Optimization:** |
| 149 | +- Write efficient code by default — correct algorithm, appropriate data structures, no unnecessary allocations |
| 150 | +- Profile before micro-optimizing; measure after |
| 151 | + |
| 152 | +**Cargo.toml lints:** |
| 153 | +```toml |
| 154 | +[lints.clippy] |
| 155 | +pedantic = { level = "warn", priority = -1 } |
| 156 | +# Panic prevention |
| 157 | +unwrap_used = "deny" |
| 158 | +expect_used = "warn" |
| 159 | +panic = "deny" |
| 160 | +panic_in_result_fn = "deny" |
| 161 | +unimplemented = "deny" |
| 162 | +# No cheating |
| 163 | +allow_attributes = "deny" |
| 164 | +# Code hygiene |
| 165 | +dbg_macro = "deny" |
| 166 | +todo = "deny" |
| 167 | +print_stdout = "deny" |
| 168 | +print_stderr = "deny" |
| 169 | +# Safety |
| 170 | +await_holding_lock = "deny" |
| 171 | +large_futures = "deny" |
| 172 | +exit = "deny" |
| 173 | +mem_forget = "deny" |
| 174 | +# Pedantic relaxations (too noisy) |
| 175 | +module_name_repetitions = "allow" |
| 176 | +similar_names = "allow" |
| 177 | +``` |
| 178 | + |
| 179 | +### Bash |
| 180 | + |
| 181 | +All scripts must start with `set -euo pipefail`. Lint: `shellcheck script.sh && shfmt -d script.sh` |
| 182 | + |
| 183 | +### GitHub Actions |
| 184 | + |
| 185 | +Pin actions to SHA hashes with version comments: `actions/checkout@<full-sha> # vX.Y.Z` (use `persist-credentials: false`). Scan workflows with `zizmor` before committing. Configure Dependabot with 7-day cooldowns and grouped updates. |
| 186 | + |
| 187 | +## Workflow |
| 188 | + |
| 189 | +**Before committing:** |
| 190 | +1. Re-read your changes for unnecessary complexity, redundant code, and unclear naming |
| 191 | +2. Run relevant tests — not the full suite |
| 192 | +3. Run linters and type checker — fix everything before committing |
| 193 | + |
| 194 | +**Commits:** |
| 195 | +- Imperative mood, ≤72 char subject line, one logical change per commit |
| 196 | +- Never amend/rebase commits already pushed to shared branches |
| 197 | +- Never push directly to main — use feature branches and PRs |
| 198 | +- Never commit secrets, API keys, or credentials — use `.env` files (gitignored) and environment variables |
| 199 | + |
| 200 | +**Hooks and worktrees:** |
| 201 | +- Install prek in every repo (`prek install`). Run `prek run` before committing. Configure auto-updates: `prek auto-update --cooldown-days 7` |
| 202 | +- Parallel subagents require worktrees. Each subagent MUST work in its own worktree (`wt switch <branch>`), not the main repo. Never share working directories. |
| 203 | + |
| 204 | +**Pull requests:** |
| 205 | +Describe what the code does now — not discarded approaches, prior iterations, or alternatives. Only describe what's in the diff. |
| 206 | + |
| 207 | +Use plain, factual language. A bug fix is a bug fix, not a "critical stability improvement." Avoid: critical, crucial, essential, significant, comprehensive, robust, elegant. |
0 commit comments