# docs-main-2026-03-13-integration-report

## 测试范围与类型选择

- 类型：集成验证
- 范围：`.agents/skills/docs-main` 的内容修正、skills 分发同步与一致性校验
- 原因：本次变更涉及共享 skill 定义与多目录分发，不涉及业务代码逻辑，适合集成验证

## 检查结论

- 结论：需要修正，且修正后更合理
- 原因 1：原 `docs-main` 引用了不存在的 `references/project-overview.md`
- 原因 2：原 `docs-main` 将“文档与代码冲突时以代码为准更新文档”写成默认规则，违反仓库“文档即契约、冲突必须停下确认”的要求
- 原因 3：原 `docs-main` 的模板路径写成 `references/templates/...`，与当前实际目录结构不一致
- 原因 4：原 `docs-main` 对自身定位不够清晰，容易让 AI 误把 skill 当成文档事实源，而不是文档工作流入口

## 修正内容

- 明确 `docs-main` 是“文档流程 skill”，不是事实源
- 增加必读入口，指向 `docs/standards/06-documentation-system.md`、`docs/standards/README.md`、`docs/standards/01-workflow/09-ai-first-development-workflow.md`
- 修正模板路径为 `references/*.md`
- 删除失效引用
- 将冲突处理改为“必须停下并等待用户确认”
- 补充面向 AI-first 项目的工作流、边界与验证建议

## 执行记录

- 已执行：`npm run sync:skills`
  - 结果：通过，`.agents/skills/` 已同步到 `.claude/skills/`、`.codex/skills/`、`.cursor/skills/`
- 已执行：`bash scripts/check-agent-assets.sh`
  - 结果：通过，分发目录与共享源一致
- 已执行：`diff -qr .agents/skills .claude/skills`
  - 结果：通过，无差异

## 最小复现步骤

1. 修改 `.agents/skills/docs-main/SKILL.md`
2. 执行 `npm run sync:skills`
3. 执行 `bash scripts/check-agent-assets.sh`
4. 执行 `diff -qr .agents/skills .claude/skills`

## 结果

- 结论：通过
- 影响范围：`docs-main` skill 定义、共享 skills 索引、多工具分发目录
- 阻断项：无