181 lines
5.6 KiB
Markdown
181 lines
5.6 KiB
Markdown
# Claude Code Working Rules
|
|
|
|
## Mandatory command constraints
|
|
|
|
These rules exist because previous long shell commands and streamed responses
|
|
caused tool failures.
|
|
|
|
- Do not use heredocs.
|
|
- Do not use long `node -e` commands.
|
|
- Do not use long `python -c` commands.
|
|
- If helper code is needed, create a small script file and run it.
|
|
- Keep shell commands short and readable.
|
|
- Break complex work into several commands.
|
|
- Write large outputs to files instead of printing them.
|
|
- Do not print full JSON responses or graph objects.
|
|
- Do not paste complete large files into chat.
|
|
- Prefer: tool → file → concise summary.
|
|
- Keep final reports concise.
|
|
- Do not narrate every implementation step.
|
|
|
|
## Change discipline
|
|
|
|
Before editing:
|
|
|
|
1. state the current branch;
|
|
2. inspect `git status`;
|
|
3. identify the relevant files;
|
|
4. explain the smallest intended change.
|
|
|
|
Work on one component or concern at a time.
|
|
|
|
Do not combine unrelated cleanup with the requested task.
|
|
|
|
Do not reformat unrelated files.
|
|
|
|
Do not modify production reasoning code during UX tasks.
|
|
|
|
## Testing discipline
|
|
|
|
Use focused tests.
|
|
|
|
Do not run the full test suite unless requested or genuinely necessary.
|
|
|
|
Do not call Ollama in unit tests.
|
|
|
|
Do not run live multi-scenario evaluations for ordinary UI changes.
|
|
|
|
Do not run Playwright unless the task specifically requires it.
|
|
|
|
Do not weaken existing reasoning tests to make UI changes pass.
|
|
|
|
## Git discipline
|
|
|
|
Before committing:
|
|
|
|
- inspect the diff;
|
|
- confirm no secrets;
|
|
- confirm no internal IP addresses;
|
|
- confirm no raw provider responses;
|
|
- confirm no screenshots;
|
|
- confirm no temporary scripts;
|
|
- confirm no generated test outputs;
|
|
- confirm only intended files changed.
|
|
|
|
Use a focused commit message.
|
|
|
|
Do not merge or tag unless explicitly requested.
|
|
|
|
## Non-narration rule
|
|
|
|
Claude Code must act as an implementation agent, not narrate its internal
|
|
debugging process.
|
|
|
|
When tests fail:
|
|
|
|
1. inspect the focused failure;
|
|
2. make the smallest justified edit;
|
|
3. rerun the focused test;
|
|
4. repeat until passing or genuinely blocked.
|
|
|
|
Do not print or explain intermediate reasoning.
|
|
|
|
Never print:
|
|
|
|
- rendered HTML;
|
|
- full JSON;
|
|
- full graph objects;
|
|
- large diffs;
|
|
- long stack traces;
|
|
- repeated interpretations of the same failure.
|
|
|
|
Prefer:
|
|
|
|
tool → edit → focused test → concise report
|
|
|
|
The final chat response must be under 1,000 words and normally contain only:
|
|
|
|
- branch;
|
|
- commit hash;
|
|
- files changed;
|
|
- behaviour changed;
|
|
- tests;
|
|
- lint/build;
|
|
- remaining limitation;
|
|
- git status.
|
|
|
|
## Response discipline
|
|
|
|
At the end of a task, normally report only:
|
|
|
|
- branch;
|
|
- commit hash, when committed;
|
|
- files changed;
|
|
- behaviour changed;
|
|
- tests;
|
|
- lint/build;
|
|
- manual result, if performed;
|
|
- remaining limitation;
|
|
- git status.
|
|
|
|
Stop after reporting. Do not begin the next task automatically.
|
|
|
|
When a task is interrupted by output limits, resume with a narrowly scoped repair prompt rather than restating the entire original brief.
|
|
|
|
User interfaces communicate reasoning, not implementation. If a piece of information exists only because the engine tracks it internally (graph nodes, unresolved counts, edge totals, confidence scores), it should remain in Developer Details unless it directly helps the user make their next decision.
|
|
|
|
## Playwright MCP — canonical dev server ownership
|
|
|
|
- Assume `http://localhost:3000` is already running when a task names it.
|
|
- Never start / stop / kill / restart / replace / port-probe the dev server.
|
|
- Never reinterpret "do not start/restart/kill/probe" as "start normally" or "use npm run dev".
|
|
- If the canonical dev server is unavailable: **BLOCKED** — do not proceed.
|
|
|
|
## Playwright MCP — known controls and semantic locators
|
|
|
|
For known UI controls, use **Run Playwright code** with exact semantic locators:
|
|
|
|
```js
|
|
await page.getByRole('button', { name: 'Review current understanding' }).click();
|
|
```
|
|
|
|
Do NOT first try MCP Click. Do NOT use snapshot refs (`[ref=...]`) for actions — they are observational only.
|
|
|
|
Semantic scoping is allowed and encouraged where names repeat, e.g.:
|
|
|
|
```js
|
|
page.getByRole('dialog').getByRole('button', { name: 'Restart investigation' });
|
|
```
|
|
|
|
## Playwright MCP — semantic waits
|
|
|
|
For known async/hydration states, use `waitFor` with a semantic state — not arbitrary sleeps:
|
|
|
|
```js
|
|
await page.getByRole(...).waitFor({ state: 'visible', timeout: ... });
|
|
```
|
|
|
|
Client hydration is real product behaviour. Always await before classifying localStorage-backed UI state.
|
|
|
|
## Playwright MCP — selector failure
|
|
|
|
If the prescribed semantic locator cannot find its expected control: **STOP**.
|
|
|
|
Do NOT fall back to snapshot refs, CSS selectors, XPath, DOM traversal, `page.evaluate`, aria-label guessing, or locator archaeology.
|
|
|
|
## Playwright MCP — browser state and live freeze
|
|
|
|
During live verification do not inspect / inject / mutate browser storage merely to manufacture expected test state (unless storage manipulation itself is the explicit experiment).
|
|
|
|
Once live Playwright verification begins: **NO PRODUCTION FILE EDITS**. First visible discrepancy is evidence to capture and stop on.
|
|
|
|
## Deterministic test rules — apparatus ownership
|
|
|
|
**Tests are instruments, not product truth.**
|
|
|
|
At the first deterministic failure classify: **PRODUCT FAILURE** or **APPARATUS FAILURE**, then stop.
|
|
|
|
For APPARATUS FAILURE: do not turn the product task into test-harness development. Do not enter repeated vi.mock / dynamic re-import / module-cache manipulation / duplicate render / global mutation repair loops. Route apparatus correction separately.
|
|
|
|
If a lower-layer function is mocked, test the value crossing the mocked seam — do NOT require the mock to reproduce its real implementation. Storage-layer tests own storage writes.
|