- HI1: Always respond with a numbered list, having each item as terse as possible. Long items or loose paragraphs tend to be ignored by humans.
- HI2: When making a reference to code, use a full relative file path + LoC.
Example:
api/accounts/models/user.py:36.
- S1: Do exactly what is asked. Nothing more, nothing less. Do not add features, refactor surrounding code, "improve" things, or remove things that were not part of the request. Unsolicited changes are forbidden.
- H1: No flattery. No sycophancy. Ever. User wrong = say wrong. Unsure = say unsure.
- H2: Do not underestimate the human's capacity to read code when it's well-architected. Avoid overexplaining, and overcommenting code. Only add comments that explain why, not what, when they are not obvious. If the code is too complex to need a comment, it probably needs more clarity in its engineering, and comments if any explaining is still necessary to avoid raised eyebrows in human reviews.
- CM1: A comment never describes the code. Readable code describes itself. If a comment restates what the code already says, delete it and clarify the code instead. Docstrings for public functions and classes are the exception.
- CM2: A comment exists only to reveal context that is not in the code — a dependency's behaviour, a spec, an upstream bug, an external constraint, a business rule. It reveals that context as it is, never how the code came to be. Keep it terse and one-line. Good: "Float sums drift on large totals."; "Webhooks may arrive out of order."; "Clock can jump backwards; use a monotonic source."
- CM3: No deictic comments — never reference anything that exists only in the work session, the conversation, or a draft, rather than in the code. These are deixis and are forbidden: a situation ("fixes the failing test in CI"), a debugging session ("was returning stale segments here"), team dynamics ("remove before shipping to production"), a decision process ("Decision 3: evaluate in the view"), a prior draft ("switched from offset pagination"), a discarded approach ("we no longer recompute this"). A future reader has none of that context.
- V1: NEVER GUESS. Be eager to obtain fresh information from reliable sources — such as local code and dependencies code, or Internet documentation — about any approach, or statement, or idea, before presenting or executing it. Assumptions are strictly forbidden.
- V2: Show evidence. Every claim needs proof. Run command. Read file. Fetch URL. "Search results say" is not evidence.
- V3: Verify before act. Check a thing exists before saying it exists. Test before commit.
- C1: Do it right, not fast. No template-paste. No skimming. No batching for speed. Read fully. Think fully. Act once, act right. "Good enough" is not good enough.
- C2: Fix the source, not the symptom. When a problem appears, remove its cause so it stops occurring. Workarounds, suppressions, and conditional hides are forbidden unless the root cause is genuinely out of reach and the workaround is documented as such.
- C3: Fail loud on impossible failures. If something the program cannot
function without is missing — a bundled asset, an internal invariant, a
computed value the next line consumes — abort or
push_errorrather than substituting a default and continuing. Silent fallbacks hide bugs and ship corrupted state; loud failures surface root causes. Guard inputs from outside the program (user input, network, file system entries the user controls), not against internal conditions that "cannot happen".
- D1: Always read the full documentation at docs/. Except for experimenting, only work from information present in the documentation, or propose a dialogue to update it.
- L1: Resist writing custom code. There is usually a known, efficient algorithm to solve the problem, often implemented in a library. Use it instead of writing your own.
-
T1: Two categories. Black-box integration tests live in
tests/integration/and only invoke public interfaces — HTTP endpoints, exported scene or module APIs — and verify their output. Tests for individual modules, classes, and functions live intests/unit/. Never mix the two. -
T2: Avoid class-based tests. Manage test lifecycle and dependencies through framework features — fixtures, markers, parametrisation, hooks. Read the project's shared fixture file (
conftest.pyin Python, GUT helpers in GDScript) before adding new tests. -
T3: Name every test with the template
test_{subject}__{condition}__{expected_outcome}. Example:test_get_version__valid_file_contents__returns_version_number. Double underscores separate the three parts. -
T4: Use bare
# Given+# When+# Then, or# Given / When+# Then(when setup is empty or implicit) comments to structure every test body. Do not include extra comments or narrative. -
T5: Test-Driven Development. Add or modify tests ahead of writing the code they cover.
-
T6: 100% diff coverage on every PR. Every new or modified line must be reached by a test. Verify with the project's coverage tool before opening the PR.
-
T7: Verify log output. When code emits a log event that matters for product or operations, the test must assert the event was emitted with the expected attributes (
caplogin Pytest; equivalent capture in GDScript). -
T8: Tests assert the externally-observable contract, understandable by a reader who has only the merged code. A test's existence, name, and shape must never be motivated by the development process, a just-fixed bug, an internal branch you added, or an off-code decision. One behaviour → one test; never split tests to cover implementation branches. If a test only makes sense to someone who watched it being written, delete it or rewrite it to state the contract plainly. This is CM3 applied to tests.
- A1: Artifacts stand alone. No pointing to chat context. No "this", "here", "now" that require the conversation to make sense. Commit messages, PRs, code comments, docs — the reader has no chat. Could be read in decades. Must make full sense alone.
- A2: No reviewer-directed text in artifacts. Any sentence, comment, or caveat whose function is to justify the change to whoever reviews it — provenance notes ("captured from a live run"), verification claims ("validated against X"), or defences of a prior correction — is slop. Evidence and justification belong in the conversation; the artifact serves only its future reader.
-
P1: Issues and PRs explain WHY, never HOW. The reader is a product person, not a machine. No file names. No implementation details.
-
P2: New issues follow the template below.
title: short defect or goal — WHY, not HOW <One paragraph explaining the problem or desired outcome.> ## Acceptance criteria - <Each item describes a desired result, not an implementation step.> - <Written so a product person can verify completion.> -
P3: New PRs follow the template below. Title prefix is
fix(<Context>):for defects,feat(<Context>):for features. See Conventional Commits for other prefixes.title: "fix(UI): <issue title>" or "feat(Users): <goal>" — WHY, not HOW <One paragraph: why these changes exist. Not what files changed.> ## Changes - [ ] <High-level change, understandable by a product person.> - [ ] <Check items as work progresses.> - [ ] <No file names. No implementation details.> Closes / Contributes to <issue URL> Review effort: N/5
- G1: Commit messages are a single line, 60 characters or less. Start with a verb — or adverb preceding a verb — that explains why the change exists, never how. Add Claude/model co-authorship. Never mix scopes in one commit. One concern per commit.
- G2: A commit must be a product deliverable, never an implementation detail. If the change does not deliver a user-facing result, it does not deserve its own commit. The commit message is a headline that will appear in user-facing changelogs.
- G3: Do not assume the remote name is
origin. The user might use multiple remotes. - G4: Do not expect the local
mainbranch to be up to date. It will most likely be stale.