Routing
Read only the references that match files in scope:
- Python source, tests,
pyproject.toml, or Python lockfiles: references/python.md - JavaScript, TypeScript,
package.json, or Node lockfiles: references/node-typescript.md - Rust source,
Cargo.toml, orCargo.lock: references/rust.md - Go source,
go.mod, orgo.sum: references/go.md - Shell scripts: references/shell.md
- GitHub Actions workflows or action metadata: references/github-actions.md
For mixed changes, load each matching reference and no others. Skip them for documentation or advisory tasks.
Code
- Create a shared utility only after the same pattern occurs in multiple places.
- Prefer explicit control flow and cohesive modules. Simplify or justify long, complex, deeply nested functions and interfaces with many positional parameters.
- Use the standard library or an existing dependency when it fits. Before adding or upgrading a dependency, verify its supported release and compatibility, inspect the lockfile, and follow the project's pinning and supply-chain policy.
- Fail with the operation, relevant input or state, and a useful next step; do not swallow errors.
- Delete commented-out code. Comments should explain constraints or surprising behavior.
Testing
- Test behavior rather than implementation details. Cover boundaries, malformed and empty input, failures, and intentional error paths.
- Mock only slow, non-deterministic, or external boundaries.
- For a regression or important invariant, confirm the test fails against the faulty behavior.
- Fix warnings caused by the change. If a warning cannot be removed safely, use the narrowest valid suppression and explain it.