docs: refactor agent guidance layering and plan skill extraction#512
docs: refactor agent guidance layering and plan skill extraction#512
Conversation
Greptile Summary本 PR 将 Confidence Score: 5/5纯文档变更，无代码逻辑影响，可安全合入 所有变更均为文档重构，不涉及运行时代码。三处反馈均为 P2 级别的风格与可发现性建议，不影响现有功能或开发流程的正确性。文档分层目标已完整实现。 两份计划文件顶部的 superpowers 工具引用值得关注，建议在后续修订中改为工具中立的描述
|
| Filename | Overview |
|---|---|
| AGENTS.md | 精简为薄入口文件，移除长结构镜像与 GitNexus 手册，章节骨架与 CLAUDE.md 完全对齐 |
| CLAUDE.md | 与 AGENTS.md 保持高同步，仅额外增加"Claude Code Notes"三条专属说明，内容一致性良好 |
| WORKFLOW.md | 新增仓库工作流摘要，Start Here 列表第一条自引用当前文件，存在冗余歧义 |
| docs/.vitepress/config.mts | 新增三个 contributor 文档的侧边栏入口，但 release-process.md 仍缺失于侧边栏 |
| docs/contributor/agent-workflow.md | 新增共享基础工作流文档，工具中立，层次清晰，覆盖了仓库特有规则与协作约定 |
| docs/contributor/gitnexus-optional.md | 新增 GitNexus-first 增强层文档，明确声明缺失不阻塞开发，并指向 fallback 文档 |
| docs/contributor/fallback-navigation.md | 新增无 GitNexus 手工导航文档，提供详尽的模块入口、流程描述和测试指针，内容充实 |
| docs/contributor/index.md | 更新贡献者首页，加入两个新文档链接，阅读顺序合理 |
| docs/plans/2026-04-08-agents-claude-doc-layering-and-gitnexus-optional-plan.md | 新增文档分层实施计划，顶部含工具专属 superpowers 引用，与本 PR 工具中立原则矛盾 |
| docs/plans/2026-04-08-agent-constraint-skills-roadmap-plan.md | 新增 Skills 固化实施计划，同样含工具专属 superpowers 引用，其余内容结构清晰 |
| docs/spec/2026-04-08-agents-claude-doc-layering-and-gitnexus-optional-design.md | 文档分层设计规格说明，原则清晰、旧/新措辞对照完整，兼容性策略设计合理 |
| docs/spec/2026-04-08-agent-constraint-skills-roadmap-design.md | Skills 固化路线设计规格，候选 skill 分组合理，触发边界与风险隔离策略描述清晰 |
Flowchart
%%{init: {'theme': 'neutral'}}%%
flowchart TD
A["AGENTS.md\n(通用 agent 入口)"] --> W
B["CLAUDE.md\n(Claude Code 入口)"] --> W
W["WORKFLOW.md\n(仓库工作流摘要)"] --> AW
W --> GN
AW["docs/contributor/agent-workflow.md\n(共享基础规则层)"]
GN{"GitNexus\n可用?"}
GN -- 是 --> GO["docs/contributor/gitnexus-optional.md\n(GitNexus-first 增强层)"]
GN -- 否 --> FN["docs/contributor/fallback-navigation.md\n(手工 fallback 层)"]
AW --> D["docs/contributor/architecture.*.md\n(领域架构文档层)"]
AW --> T["docs/contributor/testing.md"]
AW --> R["docs/contributor/release-process.md"]
Comments Outside Diff (1)
-
docs/.vitepress/config.mts, line 164-179 (link)release-process.md未出现在 contributor 侧边栏中WORKFLOW.md、AGENTS.md和CLAUDE.md都将docs/contributor/release-process.md列为阅读顺序中的必读文档（"release-related change 时阅读"），但该文件既不在 contributor 侧边栏，也未出现在docs/contributor/index.md的链接列表中，导致通过站点导航无法直接发现该文档。建议在当前 contributor 侧边栏中补充一条入口：{ text: '发布流程', link: '/contributor/release-process' },
Reviews (1): Last reviewed commit: "docs: refactor agent guidance layering a..." | Re-trigger Greptile
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
zhumin-zizhu
left a comment
zhumin-zizhu
left a comment
There was a problem hiding this comment.
PR Review Summary
Scope: 纯文档重构，12 个文件，+1360 / -376 行，无代码变更
Strengths
- 分层设计合理：将膨胀的 AGENTS.md/CLAUDE.md 拆成四层（根入口 → 共享规则 → 可选增强 → 领域文档），职责清晰
- GitNexus 可选化处理得当：不依赖特定工具完成必要工作流，有明确的 fallback 路径
- AGENTS.md 和 CLAUDE.md 同步性好：骨架一致，仅有 Claude Code 专属说明的微小差异
- Spec 和 Plan 质量高：skill 化路线的选择原则、优先级排序和风险考量都写得清楚
Critical Issues (1)
-
fallback-navigation.md内容冗余度过高 — 该文件 146 行，大量重复了agent-workflow.md和旧 AGENTS.md 中的信息（模块列表、runtime flows、repository rules 等）。这正是本 PR 要解决的"信息重复维护"问题，但在 fallback 文档中又重新引入了一份。后续 agent-workflow 或架构文档更新时，这里很容易遗漏同步。建议：精简 fallback-navigation.md，只保留"手工导航路径"和"如何手动做 impact review"的操作指引，模块列表和 repository rules 直接引用 agent-workflow.md 和架构文档，不要复制一份。
Important Issues (3)
-
WORKFLOW.md与agent-workflow.md存在重复段落 — Documentation Placement、Optional Tooling 等内容在两个文件中几乎相同。WORKFLOW.md 作为摘要入口应该更短，直接指向 agent-workflow.md 即可，不需要复制内容。 -
config.mts 中
_env的改动无关本 PR — 第 629 行将env改为_env是一个代码变更（虽然很小），与文档分层主题无关，应该单独提交或在 PR 描述中说明。 -
Spec/Plan 文档的 agentic worker 指令 — 两份 plan 文件开头都有
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development...这类指令。这是 superpowers 插件的内部约定，放在版本化的 docs/ 里会让非 Claude Code 用户困惑。建议移到注释或单独的 metadata 中。
Suggestions (3)
-
contributor/index.md 阅读顺序调整 — 新的阅读顺序把"贡献者与 Agent 工作流"放在第 1 位，"仓库 TODO"被移出了。对于人类贡献者来说，TODO 可能比 agent workflow 更有即时价值，建议保留 TODO 在前几位。
-
sidebar 新增项的位置 — 在 config.mts 中，"贡献者与 Agent 工作流"、"GitNexus 首选工作流"、"无 GitNexus 的手工导航"插入到了"本地开发"和"测试与验证"之间/之后。对人类开发者来说，本地开发和测试应该排在更前面，agent/GitNexus 相关的放后面更合适。
-
AGENTS.md 删除了 Code Map 和 Structure — 这些是对 agent 直接有用的快速参考信息，全部删除后 agent 需要多跳几次才能定位模块。考虑在 AGENTS.md 中至少保留一个精简版的 "Architecture Pointers"（当前已有）加上 3-5 行的 key symbol 速查。
Recommended Action
- 先处理 fallback-navigation.md 的冗余问题（Critical）
- 精简 WORKFLOW.md 与 agent-workflow.md 的重复内容
- 将 config.mts 的
_env改动说明或拆出 - 其余 Suggestions 可在后续迭代中处理
|
研究发现目前gitnexus上游会在每次analyze时强行注入智能体规约文件的gitnexus handbook板块，以及植入skills |
- Add minimal Quick Lookup to AGENTS.md and CLAUDE.md - Slim WORKFLOW.md by removing redundant Documentation Placement section - Simplify fallback-navigation.md to focus on manual navigation only - Neutralize plan headers to avoid tool-specific execution requirements - Add mandatory --skip-agents-md guidance to gitnexus-optional.md This preserves the documentation layering strategy established in 63a5ff5 by preventing GitNexus analyze from re-injecting usage blocks into thin entry documents.
soimy
left a comment
soimy
left a comment
There was a problem hiding this comment.
已完成本轮审核意见修订：
改动内容
-
入口文档精简
- 在
AGENTS.md/CLAUDE.md增加最小 Quick Lookup - 精简
WORKFLOW.md，移除冗余的 Documentation Placement 章节 - 简化
fallback-navigation.md，聚焦手动导航指引
- 在
-
Plan 文档工具中立化
- 移除两个 plan 文件 header 中的工具特定执行要求
-
GitNexus 注入问题规避
- 在
docs/contributor/gitnexus-optional.md新增 "Indexing This Repository" 章节 - 明确要求使用
gitnexus analyze --skip-agents-md以防止入口文档被重新注入使用手册 - 说明了补救措施和分层策略的保持原因
- 在
验证
- ✅ 文档构建通过
- ✅ 净减少 83 行，符合精简目标
- ✅ 保持文档分层清晰：入口薄、详细指南在专门文档
commit: 3fc6d66
2 participants
背景
AGENTS.md/CLAUDE.md直接内嵌大量工具约束与导航信息，导致根入口文件持续膨胀。目标
AGENTS.md与CLAUDE.md，保留公开入口与 Claude 兼容入口的双入口结构。实现
WORKFLOW.md作为仓库级工作流摘要入口。docs/contributor/agent-workflow.md，承载共享基础规则。docs/contributor/gitnexus-optional.md，承载 GitNexus-first 导航与影响分析路径。docs/contributor/fallback-navigation.md，承载无 GitNexus 时的手工导航与 fallback 指引。AGENTS.md/CLAUDE.md，将高重复流程下沉到 contributor 文档层。repo-doc-routing、pr-description-writer、release-note-authoring、repo-impact-analysis、release-publish-orchestration与dingtalk-real-device-testing增强路线。实现 TODO
AGENTS.md继续作为公开仓库的通用项目级智能体入口CLAUDE.md保持与AGENTS.md高同步，仅保留少量 Claude Code 专属说明验证 TODO
pnpm testpnpm run docs:build