From fdd35bb04f50ecc19448bea26d63c09994251007 Mon Sep 17 00:00:00 2001 From: carlos-alm <127798846+carlos-alm@users.noreply.github.com> Date: Fri, 27 Mar 2026 16:16:14 -0600 Subject: [PATCH 1/2] docs(claude): scope conditional instructions to avoid priority conflicts Replace unconditional "must"/"always"/"every" language with contextual guidance so agents can prioritize correctly: - Codegraph workflow: from mandatory 4-step checklist to pick-what-fits with explicit skip clause for non-code files and trivial edits - Bug mandate: from "fix the bug" (unconditional derail) to "flag it, fix if blocking" (scoped response) - Worktree: from "every session" to "before making code changes", with explicit skip for read-only tasks - Sync with main: from "always" to "before new feature work", with carve-out for continuing existing PR work --- CLAUDE.md | 23 +++++++++++++---------- 1 file changed, 13 insertions(+), 10 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 03c4d2a9..92003451 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -2,22 +2,25 @@ This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. -> **Hooks enforce code quality.** This project uses Claude Code hooks (`.claude/hooks/`) to automatically inject file-level dependency context on reads, rebuild the graph after edits, block commits with cycles or dead exports, run lint on staged files, and show diff-impact before commits. If codegraph reports an error or produces wrong results when analyzing itself, **fix the bug in the codebase**. +> **Hooks enforce code quality.** This project uses Claude Code hooks (`.claude/hooks/`) to automatically inject file-level dependency context on reads, rebuild the graph after edits, block commits with cycles or dead exports, run lint on staged files, and show diff-impact before commits. If codegraph reports an error or produces wrong results when analyzing itself, **that's a real bug** — don't work around it or ignore it. Flag it to the user and, if it's blocking the current task, fix it. > **Never document bugs as expected behavior.** If two engines (native vs WASM) produce different results, that is a bug in the less-accurate engine — not an acceptable "parity gap." Adding comments or tests that frame wrong output as "expected" blocks future agents from ever fixing it. Instead: identify the root cause, file an issue, and fix the extraction/resolution layer that produces incorrect results. The correct response to "engine A reports 8 cycles, engine B reports 11" is to fix the 3 false cycles in engine B, not to document why the difference is okay. ## Codegraph Workflow -Hooks handle: file-level deps on reads, graph rebuild after edits, commit-time checks (cycles, dead exports, diff-impact, lint). **You must actively run these for function-level understanding:** +Hooks handle: file-level deps on reads, graph rebuild after edits, commit-time checks (cycles, dead exports, diff-impact, lint). **Use these for function-level understanding when modifying source code:** ### Before modifying code: -1. `codegraph where ` — find where the symbol lives -2. `codegraph audit --quick ` — understand the structure -3. `codegraph context -T` — get full context (source, deps, callers) -4. `codegraph fn-impact -T` — check blast radius before editing +Pick the commands that fit the situation — don't run all four mechanically: +- `codegraph where ` — find where the symbol lives +- `codegraph audit --quick ` — understand the structure +- `codegraph context -T` — get full context (source, deps, callers) +- `codegraph fn-impact -T` — check blast radius before editing + +Skip these for non-code files, trivial edits, or when you already have sufficient context. ### After modifying code: -5. `codegraph diff-impact --staged -T` — verify impact before committing +- `codegraph diff-impact --staged -T` — verify impact before committing ### Navigation - `codegraph where --file ` — file inventory (symbols, imports, exports) @@ -196,13 +199,13 @@ See `docs/examples/claude-code-hooks/README.md` for details. ## Parallel Sessions -Multiple Claude Code instances run concurrently in this repo. **Every session must start with `/worktree`** to get an isolated copy of the repo before making any changes. This prevents cross-session interference entirely. +Multiple Claude Code instances may run concurrently in this repo. **Before making any code changes, run `/worktree`** to get an isolated copy. This prevents cross-session interference. Skip the worktree for read-only tasks (reviews, analysis, questions). **Safety hooks** enforce these rules automatically — see the Hooks section above. **Rules:** -- Run `/worktree` before starting work -- **Always sync with `origin/main` before starting feature work.** Run `git fetch origin && git log --oneline origin/main -10` to check recent merges. If the current branch is behind main, create a new branch from `origin/main`. Never implement features on stale branches — the work may already exist on main. +- Run `/worktree` before making changes (not needed for read-only tasks) +- **Sync with `origin/main` before starting new feature work.** Run `git fetch origin && git log --oneline origin/main -10` to check recent merges. If starting fresh and the branch is behind main, create a new branch from `origin/main`. When continuing existing PR work, sync only if needed. - Stage only files you explicitly changed - Commit with specific file paths: `git commit -m "msg"` - Ignore unexpected dirty files — they belong to another session From aa6f647ebb28892cc2719c1e696bddd11d7f19f0 Mon Sep 17 00:00:00 2001 From: carlos-alm <127798846+carlos-alm@users.noreply.github.com> Date: Fri, 27 Mar 2026 16:34:00 -0600 Subject: [PATCH 2/2] fix(docs): disambiguate skip-clause referent in codegraph workflow (#659) --- CLAUDE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CLAUDE.md b/CLAUDE.md index 92003451..446b359a 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -17,7 +17,7 @@ Pick the commands that fit the situation — don't run all four mechanically: - `codegraph context -T` — get full context (source, deps, callers) - `codegraph fn-impact -T` — check blast radius before editing -Skip these for non-code files, trivial edits, or when you already have sufficient context. +Skip the above commands for non-code files, trivial edits, or when you already have sufficient context. ### After modifying code: - `codegraph diff-impact --staged -T` — verify impact before committing