1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
|
# 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.
|
