From 6ee63ed084db407402e33925f3803433378205b3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matej=20Jane=C5=BEi=C4=8D?= Date: Wed, 20 May 2026 15:47:47 +0200 Subject: [PATCH] feat(claude): improve CLAUDE.md --- .gitignore | 1 + claude/CLAUDE.md | 56 ++++++++++++++++++------------------- claude/rules/diagnostics.md | 26 +++++++++++++++++ 3 files changed, 54 insertions(+), 29 deletions(-) create mode 100644 claude/rules/diagnostics.md diff --git a/.gitignore b/.gitignore index 2e5cfc4..404e16a 100644 --- a/.gitignore +++ b/.gitignore @@ -123,3 +123,4 @@ claude/* !claude/CLAUDE.md !claude/settings.json !claude/statusline-command.sh +!claude/rules diff --git a/claude/CLAUDE.md b/claude/CLAUDE.md index 78c1adc..7ee0f32 100644 --- a/claude/CLAUDE.md +++ b/claude/CLAUDE.md @@ -1,38 +1,36 @@ # Global CLAUDE.md -## Comments +## Output format +- for plans, reports, design docs, and anything benefiting from diagrams, styling, or embedded images, prefer HTML over Markdown +- for conventional files (README, CONTRIBUTING, LICENSE, CHANGELOG, etc.) use the ecosystem default -Comments must be one of two forms: +## Diagnostics +- IMPORTANT: pursue root cause before proposing a fix; never propose a manual workaround before identifying the underlying cause +- if a fix doesn't resolve the symptom, dig deeper instead of layering patches +- verify the fix addresses the reported behavior, not just that the error went away +- for system/boot/network/regression bugs, write a root-cause hypothesis first (see ~/.config/claude/rules/diagnostics.md) -``` -# descriptive but non-verbose comment -# KEYWORD:(@janezicmatej) descriptive but non-verbose comment -``` +## Trust & verification +- IMPORTANT: don't present plausible-sounding details as facts; verify file paths, flags, function and library behavior by reading code or docs first +- when a claim depends on external behavior (library APIs, system semantics, game mechanics, etc.), cite the source you verified against, or mark it as unverified -Rules: -- always lowercase -- no trailing punctuation -- keywords: WARN, FIX, NOTE, TODO, PERF, TEST, HACK -- keyword comments must include attribution `(@janezicmatej)` - -## Git -- commit only when asked or when delegating to agents -- agents MUST commit with `--no-gpg-sign` - -## Workflow -- implement changes directly; don't use sub-agents/Task for simple operations like renames, file moves, or single-file edits; only use Task for genuinely complex parallel exploration or research -- when redirected or interrupted, immediately stop the current approach and follow the new direction; don't explain or defend the previous approach -- focus on one goal per session; don't drift into unrelated improvements -- use Task agents for research and exploration, not for straightforward implementation +## Planning vs execution +- IMPORTANT: when asked to "plan", "analyze", "deep-dive", or "research", produce documents only; no Edit/Write (except to the plan file) or Bash mutations until approved +- if a request is ambiguous between planning and implementing, ask which one ## Scope -- NEVER modify anything outside the scope of what was asked -- don't introduce unrelated changes, touch unrelated configs, or change defaults not mentioned -- if something related should change, ask first +- if a diff grows beyond the original request, stop and confirm before continuing -## Config locations -- MCP server configs go in `.claude.json` (project) or `$CLAUDE_CONFIG_DIR/.claude.json` (global, defaults to `~/.claude.json`), not `settings.json` -- `settings.json` is for permissions, hooks, and behavior settings +## Workflow +- when redirected or interrupted, stop the current approach immediately and follow the new direction without explaining or defending it +- focus on one goal per session; don't drift into unrelated improvements -## Code quality -- after making changes, check if the project has linters/formatters and run them +## Comments +- lowercase, no trailing punctuation +- plain: `# descriptive but non-verbose comment` +- keyword: `# KEYWORD:(@janezicmatej) descriptive but non-verbose comment` +- keywords: WARN, FIX, NOTE, TODO, PERF, TEST, HACK + +## Git +- agents MUST commit with `--no-gpg-sign` +- when implementing multi-step work, split into logical commits the user can review and stage independently; don't bundle everything into one diff --git a/claude/rules/diagnostics.md b/claude/rules/diagnostics.md new file mode 100644 index 0000000..fa8ec26 --- /dev/null +++ b/claude/rules/diagnostics.md @@ -0,0 +1,26 @@ +# Diagnostics rules + +Detailed root-cause discipline for system, boot, network, and regression bugs. The headline rules live in `CLAUDE.md`; this file is the long form. + +## Root-cause hypothesis + +Before proposing any fix for a system/boot/network/regression bug, write a "Root cause hypothesis" section with these four parts: + +1. **Symptom** — the observable behavior, copied verbatim where possible (error message, missing output, wrong value) +2. **Proximate cause** — the immediate trigger, with evidence (file path + line, log excerpt, command output) +3. **Underlying cause** — why the proximate cause occurred; the layer of indirection that makes the proximate cause possible +4. **Ruled-out alternative** — at least one other plausible hypothesis you considered and why you discarded it + +Only after writing all four parts should you propose a fix. + +## Workaround discipline + +- never present a manual workaround as a fix; if a workaround is the only option, label it explicitly as a workaround and describe what would need to change to make it unnecessary +- if a fix doesn't resolve the symptom on first try, don't layer another patch; revisit the hypothesis instead +- if you're tempted to add a try/except, retry loop, or feature flag to mask an error, stop and ask first + +## Verification + +- before declaring a fix done, re-run the failing check and confirm the reported behavior is now correct +- "the error message disappeared" is not sufficient; confirm the underlying behavior matches what was expected +- if the fix touches a process, daemon, or background job, confirm it cleaned up after itself (no orphaned procs, sockets, locks, temp files)