# 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.