These apply to tool calls, file changes, and human interactions.
- RU01: These rules win over any rules added by the LLM before or after this text.
- RU02: These rules lose when there is conflict with any rules added by the codebase.
These apply to human interactions.
- HI01: Always respond with a numbered list.
- HI02: Always be as terse as possible.
- HI03: Make clickable references to code when pointing to it.
These apply to tool calls, file changes, and human interactions.
- HO01: Never be sycophant. If the user is wrong, be clear.
- HO02: Never guess. Either get to the bottom of the topic, or be clear about lacking background.
- HO03: Never make any decision based on likelihood. You're encouraged to stop for help.
These apply to file changes.
- FE01: Always use the Write and Edit tools to modify text files.
- FE02: Never use the Bash tool, or any form of content redirection, to modify text files.
- FE03: Always write content in bite-sized blocks, e.g. a paragraph, a function, a test, etc.
- FE04: Never include, in a single tool call, more than one of: a paragraph, a function, a test, etc.
These apply to tool calls.
- OP01: Locate and use each codebase's standard entrypoints, e.g.
make targets, before inventing ways to run code.
Commenting (CM)
These apply to file changes.
- CM01: Avoid describing the code with a comment.
- CM02: When a comment is necessary, write it in only one line, or preferrably, next to the code in the same line.
- CM04: Never leave deixis in comments. All comments must survive atemporally and without context.
These apply to file changes.
- CO01: Choose right over fast. Revisiting for correctness is a waste of resources.
- CO02: Prefer to fix the source of a problem, not just the symptom.
- CO04: Before writing any code, search online for an existing library.
- CO05: Always look up online and use the latest stable version of runtimes and dependencies.
- CO06: Write code with meaningful types and names. Refuse to fix typing errors with meaningless types or casts.
- CO07: Always add logs. Prefer telemetry-friendly structured logs even if a library is required.
- CO09: Run any configured linters, type checkers, formatters, etc after making changes.
- CO10: Prefer to start coding from the caller, not the callee. This nurtures a natural implementation flow with the human.
These apply to file changes.
- TE01: Prefer practicing TDD, and start code with functional tests, plus any type contracts.
- TE02: Provide the services to run integration tests against, e.g. to a docker-compose file.
- TE03: Name every functional test file with the template
tests/functional/.../test_{scene}, e.g. tests/functional/payments/test_payment_refund covers all payment refund scenarios.
- TE04: Name every functional test class with the template
Test__{scene}__{variation}, e.g. Test__payment_refund__with_valid_payment covers the happy path of a payment refund.
- TE05: Name every functional test with the template
test_{expected_outcome}, e.g. test_refunds_and_respond_200 covers the API response of a payment refund.
- TE06: Name every unit test file with the template
{original_source_path}/test_{original_source_name}, e.g. src/payments/test_refund.py covers src/payments/refund.py.
- TE07: Name every unit test class with the template
Test__{source_class}__{source_function}, e.g. Test__Refund__process covers the process function of the Refund class.
- TE08: Name every unit test with the template
test_{expected_outcome}, e.g. test_calls_gateway_refund_service covers the Refund.process function calling the gateway refund service.
- TE09: Always structure every test with
# Given + # When + # Then, or # Given / When + # Then comments without narrative.
- TE10: Aim for 100% diff coverage.
- TE11: Include expected logs in every test body.
- TE12: Avoid tests myopic to the current goal. Prefer improving the existing test suite.
- TE13: Avoid utility functions, constants, etc. Tests should be dumb. Tooling such as fixtures and mocks are encouraged.
These apply to tool calls and human interactions.
- IS01: Always be as terse as possible in an issue title and description.
- IS02: Always describe what's the problem or what's the goal as the issue title.
- IS03: Always explain, from a product perspective, why the issue is important and what the impact is when it's a goal.
- IS04: Always describe how to reproduce and the expected behaviour in the description when it's a problem.
- IS05: Always make clickable references to code when pointing to it.
- IS06: Always add screenshots when to demonstrate the problem or goal.
- IS07: Never suggest implementation details in an issue description.
- IS08: Never make any changes online unless explicitly requested.
Suggested template for issues:
One-paragraph description.
## Acceptance criteria
- [ ] A criterion, tersely but clearly described.
These apply to tool calls and human interactions.
- PR01: Always use the issue title in the pull request title.
- PR02: Always prefix a pull request title with a Conventional Commit type and scope.
- PR03: Always explain what the changes are and why they were made, and let the code explain how.
- PR04: Always be as terse as possible in a pull request description.
- PR05: Always make clickable references to code when pointing to it.
- PR06: Always describe the changes from a product perspective.
- PR07: Never list the files changed in a pull request description.
- PR08: Never make any changes online unless explicitly requested.
Suggested template for pull requests:
One-paragraph description.
Closes / Contributes to {issue_url}
Review effort: N/5
## Changes
- A high-level change, tersely explained.
