c9dbd51ed1
sql/muse compose 挂载 / 覆盖台账 JSON 是 SoT 别重生成 / 加 service @Resource 依赖须真跑跨模块 IT / 全新作品 AI 需 muse_tool_grant authz 种子 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;含跨域物化特有红线(本地键不存外域 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 |
✅ | 承接→分析→评审→执行→验证→沉淀;简单/全流程分流 + 证据门 + 构建纪律 |
三、维护规则(关键)
- 何时新增 vs 更新:全新主题→新增文件;已有主题补充/修正→更新现有文件(先查重,不造重复)。
- 过时即处理:信息失效立即修正或删除;与代码/文档冲突时以已验证事实为准。
- 单一主题、精炼、可检索:每文件聚焦一主题,多用表格;做蒸馏与索引,不照搬源文档大段内容。
- 同步索引:任何结构性变更(增/删/改名)同步更新本 README 清单 +
../AGENTS.md导航。 - rules 必配门禁:新增 rule 时必须说明其机械门禁落点(CI/ArchUnit/测试),否则它只是会被绕过的软约束(本项目教训)。
- 语言:一律简体中文;交叉引用用相对路径。
维护本身是任务收尾的一部分——见
workflows/ai-development-protocol.md的"沉淀"环节。