Skip to content

docs(claude-md): navigation contract + compressed quick-ref templates - #164

Merged
dreamlx merged 1 commit into
masterfrom
docs/158-claude-md-templates
Aug 14, 2026
Merged

docs(claude-md): navigation contract + compressed quick-ref templates#164
dreamlx merged 1 commit into
masterfrom
docs/158-claude-md-templates

Conversation

@dreamlx

@dreamlx dreamlx commented Aug 14, 2026

Copy link
Copy Markdown
Owner

#158 audit 的范围外伴随改动(issue 里预告过的 working-tree 批次):

  • 注入模板(claude_md_core*.md)大幅压缩:quick-ref 只留非显而易见命令 + escape hatch,完整参考委托 codeindex --help
  • 跨模块边界写成契约:横跨 ≥2 模块的端到端链路住在宿主 repo 的 architecture/ADR,永不进 README_AI
  • 本仓 CLAUDE.md 注入段同步到新模板(codeindex claude-md update 产物)
  • CHANGELOG 记 entry;宿主 repo 会在下次 CLI 调用时收到 update hint

全套 pytest 已带这些改动验证绿(1817 passed)。

The injected section 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. Quick-ref cut to the
non-obvious commands and escape hatches (full reference delegated to
codeindex --help). Context: #158 audit's out-of-scope companion change.
@dreamlx
dreamlx merged commit f0eebbb into master Aug 14, 2026
8 checks passed
@dreamlx
dreamlx deleted the docs/158-claude-md-templates branch August 14, 2026 18:33
@dreamlx

dreamlx commented Aug 16, 2026

Copy link
Copy Markdown
Owner Author

v0.37.0 回归:注入模板删掉了 hooks rerun escape hatch

#164 压缩模板时特意保留了两个非显而易见的 escape hatch(scan-all --ai --retry-allhooks rerun post-commit,"escape hatch 必须与 cache/idempotent 命令同处,不能省略到 --help"——AI 命中 cache 看起来像 bug,会 destructive workaround 或浪费 round-trip 问用户)。

实测 v0.37.0 注入产物(lh-enterprise CLAUDE.md):

-完整参考:`codeindex --help`。非显而易见的两个:
+完整参考:`codeindex --help`。非显而易见的一个:
-codeindex hooks rerun post-commit     # 对 HEAD 强制重跑 hook(绕过 loop guard)

hooks rerun post-commit 被移出,且措辞从"两个"改为"一个"——是有人有意删的(不是渲染 bug)。

建议:恢复它。这个命令恰恰是最典型的"AI 命中坑后才需要"的 escape hatch——post-commit hook 因 doc-only commit / loop guard 漏跑时,agent 看到的症状是"README_AI 落后于 HEAD",没有这条命令的第一反应往往是重跑 scan-all(重、且误解根因)。约一行成本。

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant