diff --git a/CHANGELOG.md b/CHANGELOG.md index 5643437..cb434bb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +### Changed + +- **CLAUDE.md injection templates compressed, navigation contract hardened** + (GH #158 context). The injected section now states the cross-module + boundary as a contract: end-to-end flows spanning ≥2 modules live in the + host repo's architecture docs / ADRs, never in README_AI. The quick-ref + was cut to the non-obvious commands and escape hatches (full reference + delegated to `codeindex --help`), keeping the injection small. Host repos + pick this up via `codeindex claude-md update` (the startup hint + flags it). + ### Fixed - **CLAUDE.md outdated-hint: one version source + stderr** (GH #161). diff --git a/CLAUDE.md b/CLAUDE.md index 83f5344..2ffd0cc 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -227,3 +227,31 @@ Guide: `docs/guides/git-hooks-integration.md` 4. **Ignore README_AI.md** → Always read it first. 5. **Commit to develop/master directly** → Use feature branches. 6. **Forget venv** → Always `source .venv/bin/activate` first. + + +## codeindex + +This project uses [codeindex](https://github.com/dreamlx/codeindex) (v0.35.1) for AI-friendly code documentation. + +### Navigation contract + +`README_AI.md` is a **navigation index**, not authoritative technical documentation — orient with it ("what/where is X"), then read source via Read/Grep for precise mechanism. Cross-module flows (end-to-end chains spanning ≥2 modules) are out of scope: they live in the host repo's architecture docs / ADRs, never here. Symbol-level queries (calls/references/definitions): Serena MCP (`find_symbol`, `find_referencing_symbols`). + +### Commands & escape hatches + +Full reference: `codeindex --help`. The non-obvious ones: + +```bash +codeindex scan-all --ai --retry-all # force re-enrich every dir, ignore cache +codeindex hooks rerun post-commit # force-rerun hook vs HEAD (bypasses loop guard) +``` + +Transient AI failures (`⚠ : AI error`) → re-run `codeindex scan-all --ai`; successes restore from cache, only failures retry. Persistent → swap model in `ai_command` (`.codeindex.yaml`). + +### README_AI markers + +Each `README_AI.md` header carries: the navigation contract comment, a `Generated by ...` provenance line, and optionally `` / `` (absent = structural-only, never ran `--ai`). + +After upgrading codeindex, run `codeindex claude-md update` to refresh this section. + + diff --git a/src/codeindex/templates/claude_md_core.md b/src/codeindex/templates/claude_md_core.md index d6cb25a..4f993fc 100644 --- a/src/codeindex/templates/claude_md_core.md +++ b/src/codeindex/templates/claude_md_core.md @@ -2,70 +2,23 @@ This project uses [codeindex](https://github.com/dreamlx/codeindex) (v{version}) for AI-friendly code documentation. -### What `README_AI.md` is (and is not) +### Navigation contract -It is a **navigation index** — a per-directory summary written so you can orient quickly without reading every source file. Each `README_AI.md` has a header comment that says so explicitly: +`README_AI.md` is a **navigation index**, not authoritative technical documentation — orient with it ("what/where is X"), then read source via Read/Grep for precise mechanism. Cross-module flows (end-to-end chains spanning ≥2 modules) are out of scope: they live in the host repo's architecture docs / ADRs, never here. Symbol-level queries (calls/references/definitions): Serena MCP (`find_symbol`, `find_referencing_symbols`). -``` - -``` - -It is **not** authoritative technical documentation. Treat it as a map, then read the source files for precise behavior. - -### Code Navigation Priority - -1. **Read `README_AI.md` first** — for "what does X do" / "where is X", trust the navigation summary; for "how does X actually work" / specific mechanism, drill into source via Read/Grep (the README may oversimplify) -2. Use Serena MCP symbolic tools (`find_symbol`, `find_referencing_symbols`) for precise cross-file symbol queries (calls, references, definitions) - -### Quick Commands - -```bash -codeindex scan-all # All indexes (structural — no AI cost) -codeindex scan-all --ai # + AI per-module description; ok results cached -codeindex scan-all --ai --retry-all # Force re-enrich every dir, ignore cache -codeindex scan ./path # Scan single directory -codeindex scan ./path --ai # AI-enhanced single dir -codeindex symbols # Global symbol index (PROJECT_SYMBOLS.md) -codeindex status # Check index coverage -codeindex --help # Full command reference -``` +### Commands & escape hatches -### When `scan-all --ai` fails on some dirs - -You will see lines like `⚠ : AI error — `. Likely transient (rate limit / network). - -- Re-run `codeindex scan-all --ai` — successful dirs are restored from cache (no AI cost), only failed ones retry -- If failures persist, swap the model or backend by editing `ai_command` in `.codeindex.yaml` (see `codeindex --help` for the recipe) - -### When the post-commit hook didn't fire - -The installed post-commit hook regenerates `README_AI.md` for changed directories after each commit. It can miss a commit when: - -- the commit was doc-only (only `README_AI.md` / `PROJECT_INDEX.md`) — the shell wrapper skips those to avoid an infinite loop; -- you just flipped `hooks.post_commit.enabled: false → true` and want to retroactively populate READMEs for prior commits; -- a historical stale README predates the merge-commit fix (#84). - -Force-rerun the hook against `HEAD` (bypasses the shell wrapper's loop guard; runs the Python logic directly): +Full reference: `codeindex --help`. The non-obvious ones: ```bash -codeindex hooks rerun post-commit +codeindex scan-all --ai --retry-all # force re-enrich every dir, ignore cache +codeindex hooks rerun post-commit # force-rerun hook vs HEAD (bypasses loop guard) ``` -For a full re-scan (every directory, not just `HEAD`'s affected set), use `codeindex scan-all`. - -### What the markers mean - -Every `README_AI.md` starts with three HTML comments (the third only on AI-enriched READMEs): - -1. The navigation contract comment (shown at the top of every README since v0.24) -2. `` — provenance -3. `` / `` / *absent* — AI enrichment status +Transient AI failures (`⚠ : AI error`) → re-run `codeindex scan-all --ai`; successes restore from cache, only failures retry. Persistent → swap model in `ai_command` (`.codeindex.yaml`). -Possible enrichment-marker values: +### README_AI markers -- `` — AI description in the `> blockquote` is current -- `` — enrichment was attempted and failed; description may be missing -- No marker — structural-only (no `--ai` was run) +Each `README_AI.md` header carries: the navigation contract comment, a `Generated by ...` provenance line, and optionally `` / `` (absent = structural-only, never ran `--ai`). After upgrading codeindex, run `codeindex claude-md update` to refresh this section. diff --git a/src/codeindex/templates/claude_md_core_zh.md b/src/codeindex/templates/claude_md_core_zh.md index 9c4b6ca..574b2ae 100644 --- a/src/codeindex/templates/claude_md_core_zh.md +++ b/src/codeindex/templates/claude_md_core_zh.md @@ -2,70 +2,23 @@ 本项目使用 [codeindex](https://github.com/dreamlx/codeindex) (v{version}) 生成面向 AI 的代码文档。 -### `README_AI.md` 是什么（不是什么） +### 导航契约 -它是一份**导航索引**——按目录组织的摘要，让你无需通读每个源文件就能快速定位。每个 `README_AI.md` 开头都有一行注释明确声明这一点： +`README_AI.md` 是**导航索引**，不是权威技术文档——"X 是什么 / X 在哪" 信任导航摘要定位，"X 到底怎么工作" 用 Read/Grep 钻进源码。跨模块流程（横跨 ≥2 模块的端到端链路）不在其职责内：住在宿主 repo 的 architecture 文档 / ADR 里，永不进 README_AI。精确的跨文件符号查询（调用/引用/定义）用 Serena MCP（`find_symbol`、`find_referencing_symbols`）。 -``` - -``` - -它**不是**权威技术文档。把它当地图用，定位后再读源码确认精确行为。 - -### 代码导航优先级 - -1. **先读 `README_AI.md`** —— "X 是什么 / X 在哪" 信任导航摘要；"X 到底怎么工作 / 具体机制" 用 Read/Grep 钻进源码（README 可能过度简化） -2. 精确的跨文件符号查询（调用、引用、定义）用 Serena MCP 符号工具（`find_symbol`、`find_referencing_symbols`） - -### 常用命令 - -```bash -codeindex scan-all # 全部索引（结构化——无 AI 成本） -codeindex scan-all --ai # + 每模块 AI 描述；ok 结果走缓存 -codeindex scan-all --ai --retry-all # 强制重新 enrich 每个目录，忽略缓存 -codeindex scan ./path # 扫描单个目录 -codeindex scan ./path --ai # AI 增强单目录 -codeindex symbols # 全局符号索引（PROJECT_SYMBOLS.md） -codeindex status # 检查索引覆盖率 -codeindex --help # 完整命令参考 -``` +### 命令与 escape hatch -### 当 `scan-all --ai` 在某些目录失败 - -你会看到形如 `⚠ : AI error — ` 的行。多半是瞬时问题（限流 / 网络）。 - -- 重跑 `codeindex scan-all --ai` —— 成功的目录从缓存恢复（无 AI 成本），只重试失败的 -- 若持续失败，编辑 `.codeindex.yaml` 里的 `ai_command` 换模型或后端（配方见 `codeindex --help`） - -### 当 post-commit hook 没触发 - -已安装的 post-commit hook 在每次 commit 后为变更目录重新生成 `README_AI.md`。以下情况会漏跑： - -- commit 是纯文档（只有 `README_AI.md` / `PROJECT_INDEX.md`）—— shell wrapper 跳过这类 commit 以防无限循环； -- 你刚把 `hooks.post_commit.enabled: false → true`，想回溯补齐之前 commit 的 README； -- 历史 stale README 早于 merge-commit 修复（#84）。 - -对 `HEAD` 强制重跑（绕过 shell wrapper 的 loop guard，直接跑 Python 逻辑）： +完整参考：`codeindex --help`。非显而易见的两个： ```bash -codeindex hooks rerun post-commit +codeindex scan-all --ai --retry-all # 强制重新 enrich 每个目录，忽略缓存 +codeindex hooks rerun post-commit # 对 HEAD 强制重跑 hook（绕过 loop guard） ``` -若要全量重扫（每个目录，不只是 `HEAD` 的 affected 集合），用 `codeindex scan-all`。 - -### 标记（marker）含义 - -每个 `README_AI.md` 以三个 HTML 注释开头（第三个仅出现在经 AI enrich 的 README 上）： - -1. 导航契约注释（每个 README 顶部都有，自 v0.24 起） -2. `` —— 来源溯源 -3. `` / `` / *缺失* —— AI enrichment 状态 +瞬时 AI 失败（`⚠ : AI error`）→ 重跑 `codeindex scan-all --ai`，成功目录走缓存只重试失败的；持续失败 → 改 `.codeindex.yaml` 的 `ai_command` 换模型。 -enrichment 标记的可能取值： +### README_AI 标记 -- `` —— `> 引用块` 里的 AI 描述是最新的 -- `` —— enrich 尝试过但失败；描述可能缺失 -- 无标记 —— 仅结构化（没跑过 `--ai`） +每个 `README_AI.md` 头部带：导航契约注释、`Generated by ...` 溯源行、可选的 ``（缺失 = 仅结构化，没跑过 `--ai`）。 升级 codeindex 后，运行 `codeindex claude-md update` 刷新本段。