329db944ff
排查发现进度数字三套互相矛盾:总览/现状基线/主台账历史段=147/86、agent-specs=100/127、module-reality=233/0。核机械真值:覆盖 JSON summary=233/233 completed/0 needs(每 op 带 testFiles 证据 + P1rApiCoverageReportTest 校验 summary 自算防手工拨)。⚠️ JSON generatedAt=2026-05-25 未随内容刷新(手工维护痕迹),已在文档标注以 summary+testFiles 为准。
修正:① 总览(我上轮新建,误抄过时台账)147/233→233/233、各域 full、接口门≠端到端两口径分清、定位为人读封面(权威以台账/JSON为准);② 主台账 头部加机械源口径声明(233/0)+门禁中→满+验收债标已清零;③ 现状基线降级为 2026-06-13 历史快照(顶部时效横幅+性质去SSOT);④ AGENTS序2/module-reality 改引用;⑤ agent-specs/.agent 注记历史数字;⑥ meta-schema review 回指 execution v0.2 已证伪地基(待决策提案);⑦ design-docs/00 加'设计≠进度';⑧ dev-baseline 申明旧 SSOT 自称失效。
确立单一真实源:设计=design-docs;进度=进度总账(叙述)+覆盖JSON(机械);人读=项目功能与进度总览(封面)。
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
.agents/ —— oh-my-muse 的 Agent 能力中枢
本目录沉淀项目的全部 Agent 能力、知识、规则与流程,让团队在长期 AI 驱动开发中复利式积累,持续提升 agent 编码的能力、准确率与稳定性。 项目工作入口、定位、目录见根
../AGENTS.md(项目唯一入口);CLAUDE.md是 design-docs(设计 SSOT)的写作规范,亦从属于 AGENTS.md。设计原则(本项目特有,来自对抗复盘):机械门禁优先。本项目的失控根因是"假绿"——软约束被绕过。故
.agents/的规则不止是文档纪律,必须配套机械门禁(CI/ArchUnit/契约校验),见rules/verification-and-anti-false-green.md。
一、目录结构与职责
| 子目录 | 职责 | 回答的问题 |
|---|---|---|
knowledge/ |
事实与蓝图的蒸馏(产品、架构、模块现状基线、关键决策) | 是什么 |
rules/ |
必须遵守的硬约束 + 其机械门禁 | 必须怎样 |
skills/ |
可复用操作手册 playbook | 怎么做某一类事 |
workflows/ |
元流程(如何承接→分析→评审→执行→验证→沉淀一个任务) | 如何承接任务 |
通用顺序:先 knowledge 对齐事实 → 看 rules 划红线(且红线有机械门禁兜底)→ 用 skills 落地 → 按 workflows 推进与收尾。
二、文件清单(✅ 已建 / ⏳ 建设中)
rules/
| 文件 | 状态 | 一句话 |
|---|---|---|
rules/verification-and-anti-false-green.md |
✅ | 脊柱规则:完成=机械验证、机械门禁优先、反假绿(P0 已落地首批门禁) |
rules/bc-boundaries.md |
✅ | BC 边界:禁跨域 .dal 直连,ArchUnit 机械约束(已知违例 ContentMuseWorkOwnerFacade 单点登记整改) |
rules/contract-first.md |
✅ | 契约先行:API=docs/api-contracts/*、DB=sql/muse/V* 原地 SSOT;Flyway 卫生 + OpenAPI 结构 机械门禁(openapi-diff 已接 root workflow,远端首跑待确认) |
rules/engineering-conventions.md |
✅ | 工程约定:最小变更、契约协作、测试完成口径、CI/发布/回滚;已收敛 dev-baseline global 01-04 |
rules/security-and-reliability.md |
✅ | 安全可靠:可信边界、外部依赖 fail-closed、幂等补偿、日志审计;已收敛 dev-baseline global 05-06 |
knowledge/
| 文件 | 状态 | 一句话 |
|---|---|---|
knowledge/project-and-architecture.md |
✅ | Muse 定位 / 意图 / 非目标、最高不变式、工程底座、7 BC 职责与约束(蒸馏 design-docs) |
knowledge/module-reality-baseline.md |
✅ | 模块真实现状指针(指向现状基线 spec + 对抗复盘)+ 基建复利进展 |
knowledge/tech-decisions.md |
✅ | 已确认架构决策蒸馏(指向 架构-03-ADR + CLAUDE.md 决策表) |
knowledge/external-deps-and-gotchas.md |
✅ | 外部依赖(New-API/RAGFlow 地址·凭据来源)+ 集成兼容坑 + 前端/构建坑(蒸馏自已清理 memorys) |
skills/
| 文件 | 状态 | 一句话 |
|---|---|---|
skills/golden-journey-vertical-slice.md |
✅ | "完成"的样板:三指标 + 关 mock(MSW dev-only)+ 真后端真库 + IT/Playwright 端到端 |
skills/add-business-module.md |
✅ | 新增 muse-module(BC)标准步骤:两子模块 + 契约 + 迁移 + 注册 + 守 BC 门禁 |
workflows/
| 文件 | 状态 | 一句话 |
|---|---|---|
workflows/ai-development-protocol.md |
✅ | 承接→分析→评审→执行→验证→沉淀;简单/全流程分流 + 证据门 + 构建纪律 |
三、维护规则(关键)
- 何时新增 vs 更新:全新主题→新增文件;已有主题补充/修正→更新现有文件(先查重,不造重复)。
- 过时即处理:信息失效立即修正或删除;与代码/文档冲突时以已验证事实为准。
- 单一主题、精炼、可检索:每文件聚焦一主题,多用表格;做蒸馏与索引,不照搬源文档大段内容。
- 同步索引:任何结构性变更(增/删/改名)同步更新本 README 清单 +
../AGENTS.md导航。 - rules 必配门禁:新增 rule 时必须说明其机械门禁落点(CI/ArchUnit/测试),否则它只是会被绕过的软约束(本项目教训)。
- 语言:一律简体中文;交叉引用用相对路径。
维护本身是任务收尾的一部分——见
workflows/ai-development-protocol.md的"沉淀"环节。