文档感知模式实战：用claudex-loop的CONTEXT.md术语表与ADR沉淀项目决策

文档感知模式实战用claudex-loop的CONTEXT.md术语表与ADR沉淀项目决策【免费下载链接】claudex-loopClaude Code skill: four-phase plan hardening (recon, interrogate, Codex adversarial review, cross-model build inspection) — two AI models harden your plan before a line of code exists, then swap jobs to build it. Whoever built it never grades it.项目地址: https://gitcode.com/gh_mirrors/gr/claudex-loop用 AI 写代码时最隐蔽的坑是鸡同鸭讲——你嘴里的订单AI 理解的可能是交易代码就朝着错误的方向狂奔。claudex-loop的文档感知模式docs-aware mode就是为此而生它让 Claude Code 在计划访谈阶段自动加载项目的CONTEXT.md 术语表与ADR架构决策记录把模糊的口头共识沉淀成可追溯的项目决策文档让人和 AI 说同一套话变成默认行为 文档感知模式是怎么自动触发的claudex-loop 是一个 Claude Code 技能走四个阶段RECON侦察→ INTERROGATE访谈→ REVIEWCodex 对抗评审→ BUILD可选交叉模型构建。文档感知模式不需要额外开关。在 skills/claudex-loop/SKILL.md 中Phase 0 侦察阶段会主动寻找仓库里的活文档根目录的CONTEXT.md或大型多域仓库的CONTEXT-MAP.mddocs/adr/目录下的架构决策记录只要这些文件存在Phase 1 访谈就会自动进入文档感知模式见 skills/claudex-loop/SKILL.md。绿地项目没有现成文档也没关系——它会在第一个术语被敲定时惰性创建绝不提前建空文件。访谈中的五个动作术语冲突当场解决进入文档感知模式后访谈不再是泛泛而谈的问答而是带着词典和案卷进行。根据 skills/claudex-loop/SKILL.md 的定义每个动作都有明确职责动作说明强制术语表你的措辞与CONTEXT.md定义冲突时当场停下来让你二选一收紧模糊词对含糊或一词多义的表述先给出规范替换词再继续对话场景压测边界两个概念混淆时构造具体边缘场景逼出分界线对照代码验证你声称系统如何工作AI 去源码核对有出入就提出质疑持续维护术语表每敲定一个术语就更新CONTEXT.md只收词汇、不收实现细节旧版技能 legacy/grill-with-docs-codex/SKILL.md 里有三个典型例子很能说明这种较真术语冲突你的术语表把 cancellation 定义为 X但你看起来想说的是 Y——到底哪个模糊词你说的是 account——指 Customer 还是 User这是两回事。代码核对代码里取消的是整个 Order但你刚说支持部分取消——哪个才对编写 CONTEXT.md 术语表只收录域词汇拒绝实现细节术语表是文档感知模式的基石格式规范在 skills/claudex-loop/CONTEXT-FORMAT.md。核心原则一句话它只是术语表其他什么都不是——不放规格、不放草稿、不放实现细节。一个标准片段长这样# {项目或上下文名称} {一句话这个上下文覆盖什么。} ## Terms **Deal** One negotiated agreement with one sponsor, containing its deliverables. Not: campaign, contract, engagement **Milestone** A payment checkpoint on a deal with an amount and a due date. Not: invoice, installment四条实用规则见 skills/claudex-loop/CONTEXT-FORMAT.md一个概念一个规范词——竞争同义词全部写进Not:行禁止关系明确可见定义只说是什么一两句封顶描述行为的应该去代码或计划里只收领域术语——retry、handler、cache 这种程序员到处都认识的概念无论出现多频繁都不收录惰性创建——第一个术语真正敲定时才建文件。ADR 三段测试不是所有决定都值得留痕不是每个决策都值得写 ADR。skills/claudex-loop/ADR-FORMAT.md 设了三段测试三条同时成立才值得记录反转代价高昂——容易撤销的选择不需要记录直接撤就行未来的读者会困惑——如果代码本身就能解释这个选择记录就是冗余经过了真实取舍——我们只做了唯一合理的选择记下来毫无意义。ADR 本身刻意极简见 skills/claudex-loop/ADR-FORMAT.md一段话说清背景、决定了什么、为什么文件按0001-slug.md顺序编号放在docs/adr/。额外章节Alternatives、Consequences只有在真的值回字数时才加。典型的通过案例见 skills/claudex-loop/ADR-FORMAT.md仓库布局、事件溯源 vs CRUD、数据库选型、刻意偏离常规工程师直觉的选择以及代码里看不出来的隐性约束合规要求、伙伴 SLA 等。一次完整的文档感知实战流程把前面的机制串起来一次典型的 claudex-loop 运行是这样的侦察Claude 先探索代码库发现根目录有CONTEXT.md和docs/adr/全部加载——项目已有的词汇表和先例决策进入上下文访谈术语冲突当场澄清每敲定一个术语CONTEXT.md同步更新留痕出现难反转 会困惑 真实取舍的决策时提议写 ADR 存入docs/adr/锁定计划决策图全部打勾后PLAN.md用术语表中的规范词写成并链接相关 ADR见 skills/claudex-loop/SKILL.md交叉评审OpenAI Codex 在只读沙箱里攻击这份计划读评审时同样以CONTEXT.md作为领域语言的裁判依据。最终你会收获四份活文档PLAN.md做什么、PLAN-REVIEW-LOG.md为什么这么改、持续增长的CONTEXT.md和docs/adr/。文档不是事后补的而是决策发生的那一刻就写下的。大型多域仓库用 CONTEXT-MAP.md 划分上下文当仓库同时装了好几个业务域比如订单和计费skills/claudex-loop/CONTEXT-FORMAT.md 建议在根目录放一个CONTEXT-MAP.md列出每个上下文所在目录及它们如何通信消费什么事件、共享哪些标识。运行时的解析顺序很清晰有CONTEXT-MAP.md→ 找到与当前任务匹配的上下文有歧义会主动问你只有根CONTEXT.md→ 单上下文模式都没有 → 惰性创建根CONTEXT.mdlegacy/grill-with-docs-codex/SKILL.md 中还给了多上下文仓库的标准目录示意可作为组织自己项目的参考。快速上手安装 claudex-loop 的两种方式方式 A —— 插件安装推荐自动更新在 Claude Code 中执行/plugin marketplace add chaseai-yt/claudex-loop /plugin install claudex-loopclaudex-loop方式 B —— 手动拷贝克隆仓库后把技能复制到本地git clone https://gitcode.com/gh_mirrors/gr/claudex-loop cp -r claudex-loop/skills/* ~/.claude/skills/然后以/claudex-loop调用说 claudex this plan 也能触发。前置要求见 README.mdCodex CLI ≥ 0.130并执行过一次codex login。小结文档感知模式是自动的CONTEXT.md或docs/adr/存在时访谈自动切换为带术语表和决策记录的较真模式CONTEXT.md只做一件事——收录领域术语并显式禁用同义词它是词汇表不是设计文档ADR 靠三段测试筛选难反转、会困惑、真取舍三条齐备才落笔一段话即可配合四阶段流程侦察 → 访谈 → Codex 对抗评审 → 交叉构建项目决策从聊天记录里的口头共识变成随代码一起进仓库的活文档【免费下载链接】claudex-loopClaude Code skill: four-phase plan hardening (recon, interrogate, Codex adversarial review, cross-model build inspection) — two AI models harden your plan before a line of code exists, then swap jobs to build it. Whoever built it never grades it.项目地址: https://gitcode.com/gh_mirrors/gr/claudex-loop创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考