[RFC]: 重构 .agent 体系，提升 Agent 编程能力（progressive disclosure）

进度

项	状态	说明
P0 瘦身（progressive disclosure）	✅ 已合入	#1110
P0 其余（rules/漂移/hooks/注释规范）	🟡 PR 中	#1130：unit-test→skill、frontmatter/paths、pytest/unittest 口径、distributed/断言/commit SoT、LlamaFactory 交叉引用、AGENTS hooks、why-only 注释规则、catalog 校验脚本
P1 / P2	未开始	编排、Skill 合同深化、评估等；短 why 规范条文已在 #1130 写入 code-style，高危目录渐进改注释仍属后续

本 issue 保持 open 至 #1130 合入并确认 P0 checklist；P1/P2 另开跟进。

背景

当前仓库 .agent/（含 AGENTS.md）已有较完整的 rules / skills / agents / commands / hooks。#1110 合入后，入口膨胀与 PSA/审查双源等问题已明显缓解，但仍有：

• P0 残留：部分「流程指南」仍在 rules/（如 unit_test.md）；内容级漂移 checklist 未全部关闭；LlamaFactory 双 agent 等去重未做完
• 缺默认编排：单点 skill 齐全，但缺少统一的 plan → implement → verify → review → commit → gate 流水线约定
• 单工具耦合：.agent/settings.json 使用 Claude Code schema；hooks 跨工具可能静默失效；hooks 在 AGENTS.md 中可见性仍不足
• 工程化缺口：autogit / gate-doctor 大脚本测试不足；rules/commands frontmatter 与结构校验未完全规范化
• 源码注释信噪比（新增）：公开 API 需要 Google docstring（契约），但行内 # 常复述 what 或缺失高危 why；可借鉴 Molt「短 why、给人/AI 一遍可读」纪律，与 .agent 瘦身同一目标——降低常驻上下文与误导

业界调研依据（2025–2026）

Agent Skills 开放标准与渐进式披露

Anthropic 2025.10 将 Agent Skills 发布为开放标准（Equipping agents for the real world with Agent Skills），Claude Code、Codex CLI、Gemini CLI 均已采纳。三层加载模型已成事实标准：

• Tier 1 元数据（~100 token，常驻）：frontmatter 只放 name + description。description 是路由代码——必须写清 WHAT + WHEN + 何时不用（邻近 skill 边界），它是 agent 决定加载与否的唯一依据。
• Tier 2 SKILL.md 正文（选中后加载）：规范建议 500 行是上限，新 skill 目标 200 行以内（Agent Skills 规范及社区调研）。正文只做工作流路由和输入/输出契约，不做百科全书。本仓库目标更严：SKILL.md ≤120 行。
• Tier 3 资源（需要时才触碰）：references/（agent 读的知识）、scripts/（agent 执行的确定性代码）、assets/（输出模板）。引用保持一层深度，显式写明「何时读 / 何时跑」。

写作纪律：

• 只写当前最佳行为：现在时、无日期、无历史对比；legacy / 旧 dispatch 对照不进常驻层（可进 changelog / PR 说明）。
• 易漂移事实指向 live authority（--help、官方文档），并要求用前重验。
• 脚本只买确定性：判断密集型工作写指令；脆弱 / 重复 / 可机械验证的操作才脚本化；捆绑脚本必须实测可跑。

AGENTS.md 跨工具标准的实证数据

Morph: AGENTS.md 规范指南汇总了两项关键研究：

• Princeton 实验（Codex、10 仓库、124 个已合并 PR、Docker 隔离对照）：人工撰写的 AGENTS.md 使任务耗时中位数降 28.6%、token 降 16.6%——机制是省掉了探索目录、猜构建/测试命令的开销。
• 后续研究发现 LLM 自动生成的 AGENTS.md 反而使成功率略降、成本升 23%，原因是内容重复了仓库已有信息。

写作判据（比单纯控行数更可执行）：

• 每一行都必须是 agent 无法从代码推断的信息——非默认的风格规则、带精确 flag 的命令、明确禁区。
• 从 20–30 行起步，根据 agent 实际犯的错增补；禁止「LLM 整篇生成后无审合入」。
• 行数 / token：建议常驻 500–2000 token；本仓库目标 AGENTS.md ≤150 行。长文档一律 link 不内联。注意 Codex 默认 32 KiB 截断。
• monorepo 可嵌套 AGENTS.md（就近优先）；本仓库短期不拆包，暂不引入嵌套 AGENTS.md，避免再多一层真相。

三层配置架构

AGENTS.md vs .cursorrules vs Claude Skills 对比：AGENTS.md 是环境上下文（「我们怎么写代码」），Skills 是可调用能力（「怎么做一次发布」），MCP 是实时数据访问——三层互补，不是竞品。反模式：同一规则多处维护必然漂移；写愿望清单而不是可执行规格；忽视 token 成本。

Subagent 使用纪律

社区共识（UX Planet: Subagents 优化实践）：不要为每个任务建 subagent；subagent 的 description 是触发器不是文档。

保留 subagent 的判据（三者至少满足其一）：

1. 中间产物很吵，需隔离上下文
2. 需要工具白名单（如只读审查）
3. 需要并行委派

专家知识（代码地图、公式、故障模式）本质是可查阅知识，而非需隔离执行的任务——放 references/ 按需读，比维护 N 个厚度不一的 expert agent 更省上下文、更不易腐化。

Hooks 确定性门禁

Claude Code Hooks 生产实践：「AI 是概率性的，工程流程需要确定性保证」——每次必须发生的事（保存后 format、提交前 lint、危险命令拦截）应由 hooks 而非提示词保证。生产要点：退出码纪律（0 放行 / 非 0 阻断 + stderr 反馈给模型）、幂等性、防御性解析 payload 防 schema 漂移。

Hooks 是 harness 特定能力：跨工具会静默失效。必须明确目标 harness，并给出降级策略（例如非 Claude Code 时依赖 skill 内显式检查 + CI）。

测试与评估机制（四层）

业界先进实践要求 skill 有可执行的验收门槛（kalepail/skills 调研）：

层	内容	本仓库分期
结构校验	frontmatter schema 进 CI	P0/P1 优先
脚本实测	最小 fixture + 失败路径	P1：先罩 autogit / gate-doctor
触发评估	正例 + 难负例，度量 description 路由质量	P2：先罩 code-review / autogit / gate-doctor
行为评估	有/无 skill 干净会话对照，≥3 个代表性任务	P2：同上三件套，不全量铺开

源码可读性与短 why 注释（Molt，2026）

Molt: A Scalable PyTorch-Native Training Framework for Agentic Reinforcement Learning（NVIDIA）将 人可读 + AI coding assistant 可端到端追踪 写成一等设计原则：代码应一遍读懂控制流；需要靠第二遍或长注释才能懂 → 优先改结构，而非堆注释。仓库 simplicity-first 对行内注释的硬门禁：

• concise "why" only，约 2–4 行，写给外部读者
• 禁止：job id、commit hash、单次实验数字、内部本机路径
• 允许：upstream / 本仓 issue、PR 链接
• 能命名/结构表达清楚的，不写 what 复述

对本仓库的映射（不照搬砍 docstring）：

层	HyperParallel 做法
公开 API	继续 Google-style docstring（契约：Args/Returns/Note）
行内 #	学 Molt：只写短 why；高危处（stream/resize_(0)/ST launcher 禁 import/跨平台）缺 why 则补
规范落点	.agent/rules/code-style.md 加条目 + code-review checklist；先试点 core/dtensor、fully_shard、collectives、tests/common/*launcher*，随功能 PR 顺手改，不开全仓「注释美化」PR

仓库内已有可对齐样板：tests/common/parallel_case.py（setsid / launcher 禁 import 的 why 注释）。

参考分层

层	职责	加载时机
AGENTS.md	跨工具环境法：身份、命令、硬禁令、索引	常驻
rules/	路径触发的硬约束	按 paths
skills/	可调用工作流（SoT）	按需
agents/	隔离上下文的 worker	委派时
commands/	斜杠薄代理	显式调用
hooks/	确定性门禁（harness 特定）	工具前后

决策规则：

• Skill 改行为；Subagent 护上下文；Rule 管约束。
• 先 Skill；Skill 淹没主会话再升 Subagent。
• Agent 不得复制 Skill 公式（只跟指针）。
• 每一行常驻文案必须通过「无法从代码推断」检验。

可立刻写入规范的硬规则

落地 PR 时优先固化：

1. AGENTS.md：只写不可推断信息；禁 LLM 整篇生成后无审合入。
2. Skill description：WHAT + WHEN + 何时不用（邻近边界）。
3. 正文：当前最佳行为 only；legacy 不进常驻层。
4. 脚本：只买确定性 + 最小 fixture 测试。
5. P0 验收：已知副本 / 矛盾清单逐条关闭，并加索引一致性校验（或 CI）。
6. 行内注释（新增）：why only、宜 ≤4 行；禁 job/commit/单次指标/本机路径；公开 docstring 与行内 why 分工（契约 vs 动机）。

目标

1. 常驻上下文高信噪：AGENTS.md ≤150 行（并以「不可推断」为内容闸门）；SKILL.md 正文只做路由器（业界 ≤200 / 硬上限 500；本仓库 ≤120）
2. 单一真相：同一公式只在 skill（或 references/）维护；agent/command 只跟指针
3. 默认开发闭环可复现：澄清 → 计划 → 实现 → 验证 → 审查 → 提交 → 门禁
4. 跨工具可发现：以 AGENTS.md + .agent/skills 为 SoT；hooks 目标 harness 显式声明
5. 可验证工程化：结构校验 + 关键脚本 fixture；触发/行为评估覆盖核心 skill
6. 源码注释：高危路径有短 why；行内不靠 what 堆砌；规范进入 code-style + review

建议方案（可整体重构）

A. 分层清洗（P0）— 瘦身部分 ✅ #1110

• progressive disclosure：SKILL.md / agent 变薄，长文进 references/ / workflows/ / *-guide.md（含 gate-doctor / autogit / code-review / dist-op-dev / platform-dev / PSA）
• parallel-strategy-analyzer agent → 薄 proxy，指向 skill
• code-reviewer 薄代理 → code-review skill；simple-code-reviewer 边界标明（是否合并为 mode: quick 仍可选）
• AGENTS.md Skills/Agents 目录与磁盘对齐；Dev Commands / Env Gotchas；ST launcher 禁 import 写入 Testing 短条目
• LlamaFactory：llamafactory-hp 总览 + activation 细节进 references，避免并列双 agent
• 内容级漂移清单（仍须逐项关闭）：
  • AGENTS.md 索引表与实际 skills/agents 文件同步（#1110；是否加 CI 自动校验仍 open）
  • distributed 三处副本归一：rules/distributed.md ↔ code-review skill guidelines ↔ AGENTS.md（常驻只留 rules + link）
  • 测试断言两处副本归一：test-assertion-style.md ↔ distributed-op-testing.md
  • 提交长度口径统一到 code-style.md（~80 vs 50–72 vs 未规定）
  • pytest / unittest 三文件矛盾措辞统一口径
  • AGENTS.md hooks harness 说明补全

B. Rules 只放硬约束（P0）

• Rule = 违反即 silent bug / CI 挂；Skill / reference = 怎么写、示例、决策树
• unit_test.md 等流程指南迁出 rules/ → skill
• 补齐缺失 paths（如 multi-platform-features）
• 统一 rules/commands frontmatter schema（name / description / paths），修复 unit_test.md name 与文件名不符等问题
• 与 hooks 已覆盖的机械项缩短文案，避免模型重复背诵
• 行内短 why 注释：写入 code-style.md（3～5 条即可），与公开 Google docstring 并存

C. Skill 合同统一（P1）

每个 skill 固定三层：

1. Frontmatter：name + 第三人称 description（WHAT + WHEN + 何时不用）
2. Body：输入/输出契约、步骤清单、何时读哪个 reference（只做路由，≤120 行）
3. references/ + scripts/：大表、长 checklist、确定性脚本

写作纪律：当前最佳行为；脚本只买确定性且必须实测可跑。

重点继续脚本化并补 fixture：autogit、gate-doctor。

Skill 作者检查项（可贴在 skills/README.md）：

• description 含邻近 skill 的「何时不用」
• 正文无历史对比 / 无过期日期叙事
• 每个 reference / script 有「何时读 / 何时跑」一句说明
• 若含 scripts：至少 1 个最小成功 + 1 个失败路径 fixture

D. Agent 最小集合（P1）

仅在「吵 / 白名单 / 并行」时保留 agent。建议：

• planner（只读）
• code-reviewer（跑 code-review skill）
• code-verifier（lint/test，可进一步脚本化）
• 可选统一 domain-advisor，替代多个 expert dump；专家知识外置为 references

决策树：默认 skill/references → 主会话噪音大再升 subagent → 需要跨会话协作再考虑 agent teams（本仓库短期不需要）。

E. 主编排约定（P1）

在 AGENTS.md 或 orchestration.md 写清默认流水线：

1. planner → 计划
2. 域 skill（platform-dev / dist-op-dev / …）→ 实现
3. code-verifier → 机械门禁
4. code-reviewer（subagent）→ 分布式正确性
5. autogit → commit/PR
6. 门禁红 → gate-doctor

独立子任务同轮并行委派；有依赖则串行。

F. Hooks / 跨工具 / 可维护性（P2，结构校验可提前）

• PreToolUse：危险 git、YAML 与 impl 配对等
• 明确声明 hooks 目标 harness（当前为 Claude Code schema，文件在 .agent/settings.json），写入 AGENTS.md；非目标 harness 的降级路径（skill 显式检查 + CI）
• Cursor：可由 .agent/rules 生成/同步 .cursor/rules；补一行式 CLAUDE.md（@AGENTS.md）
• skill 标注 owner + 手测方式
• 评估分期：先结构校验 CI + autogit/gate-doctor fixture；再对 code-review / autogit / gate-doctor 做触发评估与有限行为评估

G. 源码短 why 注释（P1，可随 PR 渐进）

• code-style.md 增加行内注释硬规则（why only / ≤4 行 / 禁噪音元数据）
• code-review skill / checklist：大段 what → 删或改 why；高危缺 why → 要求补
• 试点目录随功能 PR 落地，不开全仓注释-only PR
• 样板对齐：tests/common/parallel_case.py；危险模式对齐 rules/distributed.md（规则单源，注释不重复长文）

落地顺序建议

1. P0（部分 ✅） 去重 + 瘦身 — #1110 已合入；继续关闭漂移 checklist + rules 分层清洗 + frontmatter/CI
2. P1 编排约定 + Skill 合同（含「何时不用」）+ Agent 收敛 + 关键脚本 fixture + 短 why 注释规范写入 style/review
3. P2 hooks 加强与 harness 显式化、跨工具同步、核心 skill 触发/行为评估

验收标准

• P0 瘦身主轴合入（#1110）：主要 skill 入口变薄；PSA/code-reviewer 薄代理；AGENTS 目录对齐
• AGENTS.md ≤150 行；通过「不可推断」审阅；无长版 DTensor/stream 细则复述
• 能力索引与实际文件一致（或有 CI 校验）
• 无「同一流程 agent+skill 双份维护」；审查口径唯一（simple-code-reviewer 去留已决策）
• 漂移 checklist 全部勾掉（distributed / 断言 / 提交长度 / 测试框架 / hooks 说明）
• 主要 skill 的 SKILL.md ≤120 行；description 符合路由代码规范（WHAT + WHEN + 何时不用）
• rules 均为硬约束且 paths 合理；流程类已迁出；rules/commands frontmatter schema 统一并有结构校验
• 文档中明确默认开发流水线
• hooks 目标 harness + 降级策略写入 AGENTS.md
• autogit / gate-doctor 有最小 fixture 测试；核心三 skill 有触发评估计划或结果
• 行内注释：code-style + review checklist 已含短 why 规则；试点高危路径有样板、无全仓注释-only 噪音 PR

参考来源

• Anthropic: Equipping agents for the real world with Agent Skills
• kalepail/skills: AI agent skill best practices（Codex/Claude 双平台调研）
• Morph: AGENTS.md Spec 指南（含 Princeton 实证数据）
• AGENTS.md vs .cursorrules vs Claude Skills: 2026 对比
• Claude Code Hooks 生产实践
• UX Planet: Claude Code Subagents 优化实践
• Molt (arXiv:2607.21653) + simplicity-first skill

相关

• ✅ 已合入：PR #1110 — docs(agent): slim .agent via progressive disclosure
• 🟡 进行中：PR #1130 — finish #321 remaining P0
• Issue 列表：https://gitcode.com/mindspore/hyper-parallel/issues

schema_version: 1
source: gitcode
gitcode_repo: mindspore/hyper-parallel
gitcode_issue: 321
source_url: https://gitcode.com/mindspore/hyper-parallel/issues/321

Start with .agent/AGENTS.md and the rules/, skills/, agents/, commands/, and hooks/ directories, then review the in-progress PR #1130 and completed PR #1110. Compare the remaining P0 checklist with the proposed P1/P2 work, and treat the issue as complete only when the documented acceptance criteria are resolved or split into focused follow-up issues.