# Claude Code user memory

- **Ask before spawning agents** — every agent-related decision goes through the user first.

## Harness

- **User `CLAUDE.md`** is at `$CLAUDE_CONFIG_DIR/CLAUDE.md`
- **Use todo lists extensively** — the user loves them.
  - **Empty multiple-choice answers are timeouts** — an AskUserQuestion result with no selection means the prompt timed out, not that the user chose nothing: re-ask the question, never proceed on an assumed choice.

### Shell

- **Force colour** — pass `--color=always` (or a tool's equivalent) to Bash commands that support it, so colour survives into the user's output view.
- **Monitor view** — the user follows this session's Bash in Neovim: a formatted, syntax-highlighted view of each command, and a terminal view of its output that renders ANSI colour.
- **Spell out long-form flags** — use a program's long option whenever it has one: `jq --raw-output`, not `jq -r`; `foot --app-name`, not `foot -a`.

## Git

- **No `Co-Authored-By` trailer** in commit messages.
- **Move or rename** tracked files with `git mv`.
- **Mention updating the README and `CLAUDE.md`** after committing, if relevant.
- **Commit docs in separate `type(docs)` commit** for files that are only documentation, comments are commited with the code.
- **Rewriting history on `dev` branch** is fine, don't sweat about it.

## Writing

### Code

- **Don't run formatters, linters, or checkers** yourself (hooks handle it).
- **Update doc comments with behavior:** when you change what a function or script *does*, update the comments that document it in the same edit — both the local function/block comment and the file's top/header comment.
- **Comment only current behavior** — never describe what was removed or never existed (no "X is no longer needed", "previously Y", "rather than the old Z"); if a mechanism is gone, drop it from the comment entirely.
- **Line length:** Lua 100, Markdown no hard limit, bash 80, Python 88.

### Non-code

All instructions here apply to the subsections.

- **Period** at the end of full sentences. Be consistent.
- **Trim docs** — Cut default/obvious behavior and anything docs/code already say; don't restate the same fact in two sections.
- **Lead with the point.** Open a list item with its key word(s) in bold, then the detail — so the list scans by its bold lead-ins alone.
- **Generic examples** unless there's no choice — don't bake in repo- or machine-specific paths/names when a placeholder carries the point.
- **Semantic line breaks** — add a line break after each substantial *unit of thought*, i.e. don't write unbroken blocks of text.
  **VERY IMPORTANT** — has to be applied to all prose without exception: git commit messages, `CLAUDE.md` files, READMEs, code comments, documentation, etc…
  - Default: one line per *unit of thought*.
  - *MUST* break after every sentence (`.` `!` `?`).
  - *MUST* still hard wrap — limit depends on language.
  - *SHOULD* break mid-sentence at a genuine independent clause (`;`, or `,`/`:`/`—` when a full subject-and-verb clause follows).
  - *MUST NOT* break for an appositive, elaboration, parenthetical, or introductory/dependent clause — even after `,`/`:`/`—`.

#### Comments

- **A comment** says **what** the function does (and **how**, if non-obvious). Never restate the function name and nothing else.
- **Markdown inline formatting**: backticks around identifiers, keys (`CTRL+W`), code, paths, and filetypes; UI elements in bold (`**elem**`); specific terminology emphasized (`*word*`); autolinks `<url>`.
- **Never comment individual table elements** — not inline on the element line, not on a `--` line above each element. Put one block comment above the whole table and refer to the elements by `` `value` `` in the prose.

#### Commit messages

- **Line length** — 72
- **Conventional Commits** — `type(scope): summary`, `type` one of:
  - **build** — build system or external dependencies
  - **ci** — CI configuration and scripts
  - **docs** — documentation only
  - **feat** — a new feature
  - **fix** — a bug fix
  - **perf** — a performance improvement
  - **refactor** — neither fixes a bug nor adds a feature
  - **style** — formatting only, no change in meaning (white-space, …)
  - **test** — add or correct tests
- **Scope** — optional `(noun)` naming the area touched, after the type — e.g. `feat(lsp):`, `fix(tmux):`; omit when the change is broad or has no obvious one.