oh-my-muse/.agents/README.md

.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;含跨域物化特有红线(本地键不存外域 id、隔离靠物理副本非运行时过滤、前置未就绪 fail-closed)

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)
knowledge/market-install-downstream-materialization.md	✅	market 安装下游物化机制 + KB 类型 D0-fork 私有隔离(四单元闭环、进程内事件/跨 BC 读端口/kb_id 去污染;agent handoff 物化与 KB 召回阻断已闭环,副本回收等后置)

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	✅	承接→分析→评审→执行→验证→沉淀;简单/全流程分流 + 证据门 + 构建纪律

---

三、维护规则(关键)

1. 何时新增 vs 更新:全新主题→新增文件;已有主题补充/修正→更新现有文件(先查重,不造重复)。
2. 过时即处理:信息失效立即修正或删除;与代码/文档冲突时以已验证事实为准。
3. 单一主题、精炼、可检索:每文件聚焦一主题,多用表格;做蒸馏与索引,不照搬源文档大段内容。
4. 同步索引:任何结构性变更(增/删/改名)同步更新本 README 清单 + ../AGENTS.md 导航。
5. rules 必配门禁:新增 rule 时必须说明其机械门禁落点(CI/ArchUnit/测试),否则它只是会被绕过的软约束(本项目教训)。
6. 语言:一律简体中文;交叉引用用相对路径。

维护本身是任务收尾的一部分——见 workflows/ai-development-protocol.md 的"沉淀"环节。