soia-dev-agent-md-advisor

AGENTS.md / CLAUDE.md / GEMINI.md 以及 .claude/（skills / agents / commands / hooks / settings.json）的设计顾问——审查这些文件本身写得好不好、结构合不合理，不负责它们跟项目当前状态是否同步。三种模式：①审查现有配置（诊断）②为新项目起草配置骨架（起草）③最佳实践问答。

定位与边界

与 soia-dev-doc-sync 的分界

两个技能经常被同一句话触发，但关注对象完全不同，必须分清楚：

判断规则：用户在问"这份 AI 指令文件写得好不好 / 该怎么组织"，用本技能；用户在问"文档跟实际进度/版本是否对得上"，转 soia-dev-doc-sync。两者都命中时，先用本技能诊断配置文件设计问题，状态对齐问题转交 soia-dev-doc-sync，不要在本技能里代做。

三种模式总览

模式判定由 Agent 根据输入自动进行；拿不准时先问用户"你是想审查已有的、从零起草、还是单纯问个最佳实践问题"。

客户可读说明

这个技能可以做什么

覆盖 AGENTS.md/CLAUDE.md/GEMINI.md 与 .claude/ 配置的三种工作模式：诊断已有配置的设计质量、为新项目起草配置骨架、回答最佳实践问题。本技能不调用外部 API、不读取账号或凭据、审查模式默认不写文件——纯文本诊断与产出。

客户如何使用

1. 说明诉求，并提供必要输入：审查模式给目标文件路径或全文；起草模式给项目类型、目录结构、协作 AI 数量；问答模式直接提问。
2. Agent 判定命中哪种模式；判定不了先问，不硬猜。
3. 审查模式默认只诊断，不动手改文件——这是诊断请求还是改动请求必须分清楚，客户没有明确说"帮我改/优化/执行"之前，只交付诊断报告。
4. 起草模式在项目类型/目录结构/协作 AI 数量任一项不明确时，先给一次问全的澄清清单，不脑补产出。
5. 最终回复必须包含：模式判定、诊断或产出全文、逐条说明；模式①还需给出结论等级，以及"是否已落地修改"的明确状态。

依赖与安装

安装（推荐：装整个领域插件，一次装好本仓全部技能）：

claude plugin marketplace add soia-team/soia-open-skills

claude plugin install soia-dev@soia

只要这一个技能时，可用 npx 路线。注意技能会落进共享真源 ~/.agents/skills；若同时装了插件，同一技能会出现两份索引且各自漂移，建议二选一：

npx skills add soia-team/soia-open-dev-skills -g -a '*' -s soia-dev-agent-md-advisor -y

配置约定：

~/.config/soia-skills/soia-dev-agent-md-advisor/config.yml
SOIA_DEV_AGENT_MD_ADVISOR_CONFIG_FILE=<custom-config-path>

• 本技能当前版本不需要创建 config.yml：三种模式的诊断维度、流程和模板都直接写在本 SKILL.md 内，没有需要外部化的私有状态。上述路径预留给未来"客户自定义诊断维度权重 / 长度预算阈值"这类可选增强，非必需项。
• 本技能不需要、也不应该读取任何 API key、cookie、session、账号凭据——诊断和产出只处理客户提供的文本文件和项目里可公开读取的配置文件。
• soia-dev-doc-sync 是分工邻居，不是依赖：本技能不调用它，也不做它负责的跨文档状态对账；边界见上方"与 soia-dev-doc-sync 的分界"。

WorkBuddy 的装载单位是角色化专家而不是插件，npx skills add -a '*' 覆盖不到它，需要单独安装，见 docs/install/workbuddy.md。

私密信息与中间数据

• 输入可能包含客户尚未公开的 AI 指令和项目结构；只读取本次范围内的文件，不扫描账号、vault 或无关目录，也不把原文复制进公共示例。
• 本技能不创建持久 state、cache 或独立日志。诊断草稿只留在当前 Agent 会话；宿主自身的会话留存由宿主配置管理。
• 默认只在回复中交付诊断或骨架。客户明确授权写文件时，只写目标项目中的指定文件；覆盖既有文件前必须先展示差异并确认。
• 普通 config.yml 只允许未来保存非秘密偏好；本技能不需要凭据，也不得保存 prompt、完整客户文件或响应正文。
• 回执只摘录证明 finding 所需的最小片段，并对账号、路径或其他敏感字段做脱敏。

日志与完成回执

每次执行都要让客户看见判定、诊断/产出和验证过程。最低回执格式：

完成：<一句话说明本次模式（①审查/②起草/③问答）与结果>。

日志摘要：
- 模式判定：<①/②/③，以及判定依据>
- 澄清记录：<本次问了哪些澄清问题及客户答复摘要；输入已足够时写"未追问，输入已足够">
- 诊断/产出：<模式①写六维度诊断结论与结论等级；模式②写骨架产出摘要；模式③写"不适用（问答）">

文件变化：
- <绝对路径或"未改动文件（本次仅输出诊断/建议/骨架草稿）">

问题与下一步：
- <需要客户确认的事实、占位项，或"是否要现在落地修改"；没有则写"无，可直接使用产出">

诊断维度（核心资产）

六个维度覆盖配置文件设计质量的全部检查面，逐项过，不是逐字挑刺：

诊断只报有问题的维度，通过的维度一句话带过；六项全过就如实告知"设计质量良好，暂不需要改"，不制造工作量。

模式① 审查（诊断）流程

1. 识别范围：读哪些文件——AGENTS.md、CLAUDE.md、CLAUDE.local.md、GEMINI.md、.claude/settings.json、.claude/skills//SKILL.md、.claude/agents/.md、.claude/commands/*.md、.claude/hooks/。只读与本次判断相关的文件，不为诊断而扫描整个仓库。
2. 六维度逐项诊断：对照上表逐条检查，每个问题维度定位到具体文件和行号，引用原文。
3. 判定结论等级：

- 优秀——六维度均达标 - 基本可用——1-2 项有 P2 级问题（篇幅、风格类，不直接致错） - 需要精简——问题集中在长度预算/重复与矛盾 - 需要重构——3 项以上有 P1 级问题（会导致 agent 反复犯同类错误），或分区路由整体错位 - 风险较高——存在 P0 级问题（安全边界缺失、规则自相矛盾导致行为不可预测）

1. 输出问题清单 + 改写建议，格式见下方模板。默认只诊断，不动手改文件——这是诊断请求，不是改动请求。
2. 只有客户明确说"帮我改/优化/重写/执行"，才进入落地编辑；编辑时只改被诊断出问题的部分，保留没问题的内容，不做无关的风格化重写。

输出模板

# AGENTS.md / CLAUDE.md 设计诊断

结论：优秀 / 基本可用 / 需要精简 / 需要重构 / 风险较高

## 问题清单
| 文件:行 | 维度 | 症状 | 建议改法 | 优先级 |
|---|---|---|---|---|
| `<path>:<line>` | <六维度之一> | <具体症状，引用原文> | <改法> | P0/P1/P2 |

## 做得好的地方
- ...

## 改写建议（默认不落地，等待客户确认）
- 保留：...
- 删除：...
- 拆分到子目录：...
- 合并入口：...

## 是否落地修改
- 客户尚未确认，本次仅诊断 / 客户已确认，按以下顺序修改：...

模式② 起草流程

1. 先问三件事，不确定就问，不脑补：

- 项目类型：是什么项目、技术栈、单仓还是 monorepo - 目录结构：有没有多个独立子项目/子包，分别是什么 - 协作 AI 数量：只用 Claude Code，还是同时有 Codex/Gemini/Cursor 等多个 AI 协作

1. 决定入口文件：

- 只用 Claude Code → CLAUDE.md 作为唯一入口 - 跨工具协作（Codex/Gemini/Cursor 等多个 AI）→ AGENTS.md 作为真源，CLAUDE.md/GEMINI.md 视工具支持情况做精简指针或软链接，不维护多份正文 - Monorepo/多子项目 → 根文件只放共享规则，每个子项目自己的目录下就近放一份 AGENTS.md/CLAUDE.md 承载专属规则

1. 按"根文件精简 + 子目录就近"出骨架：

- 根文件只放：项目一句话定位/技术栈/常用命令/目录地图与"新代码放哪里"规则/关键 MUST-MUST NOT/测试与完成标准/安全边界 - 子目录文件只放该目录特有、根文件用不上的规则

1. 输出骨架全文，标注哪些字段是占位、需要客户确认。不凭空发明命令——命令必须来自客户提供或项目里可验证的文件（package.json/pyproject.toml/Makefile/CI workflow 等），验证不了就写 <占位符，待确认> 并说明。

骨架模板（单仓）

# AGENTS.md

## 项目
<一句话：这是什么项目，给谁用，主技术栈>

## 常用命令
- 安装：`<command>`
- 测试：`<command>`
- 构建：`<command>`

## 目录地图
- `<path>/` - <职责>
- 新增 <类型> 代码放在 `<path>/`

## 关键规则
- MUST <关键约束>
- MUST NOT <禁止动作>

## 测试与完成标准
- <完成的验证方式>

## 安全边界
- 涉及删除/覆盖/发送/发布前先确认

Monorepo 模式

<repo>/
  AGENTS.md                     # 共享规则与路由
  <subproject-a>/AGENTS.md      # 子项目专属规则
  <subproject-b>/AGENTS.md      # 子项目专属规则

模式③ 问答流程

用简洁中文直接回答，不铺垫：

结论：...

推荐结构：
- ...

注意事项：
- ...

.claude/ 配置职责速查

判断该不该新增某个 .claude/ 子机制时用这张表，而不是默认全加：

判断原则：目录多不代表成熟，可能只是过度设计；目录缺不是问题，只要当前真的用不上。

边界与限制

• 本技能不执行代码、不跑测试、不改业务逻辑；只处理 AI 指令配置文件本身的设计质量。
• 审查模式默认只读不改；只有客户明确说"优化/重写/执行/直接改"才落地编辑，且只改诊断出问题的部分。
• 不凭空发明命令或路径；命令必须来自项目可验证来源（package.json/pyproject.toml/Makefile/CI 等）或客户提供，验证不了就标注"未核实，需客户确认"。
• 不默认建议上马复杂 .claude/agents + hooks + skills 全家桶；先判断项目是否真的需要，参考上方速查表。
• 与 soia-dev-doc-sync 不重叠：发现配置引用的路径/命令已经过时（时效维度）只是"这份文件本身该更新了"的一次性诊断，不做跨文档状态对账；真源冲突判断、release 回填、proposal 状态对齐这类工作转给 soia-dev-doc-sync，本技能不代做。
• 本技能只处理客户提供的文件或项目里可公开读取的配置文件，不读取客户的账号、vault 或无关本机文件。

完成后回执

回执包含：

1. 做了什么 — 一句话总结本次模式（①审查/②起草/③问答）、澄清情况和结果；模式①还要说明结论等级和是否已落地修改。
2. 文件变更 — 模式①默认"未改动文件（本次仅输出诊断报告）"，除非客户已确认并要求落地；模式②固定"未改动文件（本次仅输出骨架草稿，供客户确认后自行创建）"；模式③固定"未改动文件（本技能仅输出问答文本）"。
3. 下一步 — 模式①提醒客户"诊断已给出，是否需要现在落地修改"；模式②提醒客户核对骨架里的占位项和命令是否真实，确认后再落地成文件；模式③提醒客户如果想审查现有文件或起草新配置，可以切换到对应模式。