3585219637
Some checks failed
Backend Maven CI / backend-local (push) Has been cancelled
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
70 lines
5.3 KiB
Markdown
70 lines
5.3 KiB
Markdown
# .agents/ —— oh-my-muse 的 Agent 能力中枢
|
|
|
|
> 本目录沉淀项目的**全部 Agent 能力、知识、规则与流程**,让团队在长期 AI 驱动开发中**复利式积累**,持续提升 agent 编码的**能力、准确率与稳定性**。
|
|
> 项目工作入口、定位、目录见根 [`../AGENTS.md`](../AGENTS.md)(项目唯一入口);`CLAUDE.md` 是 design-docs(设计 SSOT)的写作规范,亦从属于 AGENTS.md。
|
|
>
|
|
> **设计原则(本项目特有,来自对抗复盘)**:**机械门禁优先**。本项目的失控根因是"假绿"——软约束被绕过。故 `.agents/` 的规则不止是文档纪律,**必须配套机械门禁**(CI/ArchUnit/契约校验),见 [`rules/verification-and-anti-false-green.md`](rules/verification-and-anti-false-green.md)。
|
|
|
|
---
|
|
|
|
## 一、目录结构与职责
|
|
|
|
| 子目录 | 职责 | 回答的问题 |
|
|
|---|---|---|
|
|
| `knowledge/` | 事实与蓝图的蒸馏(产品、架构、模块现状基线、关键决策) | **是什么** |
|
|
| `rules/` | 必须遵守的硬约束 + 其机械门禁 | **必须怎样** |
|
|
| `skills/` | 可复用操作手册 playbook | **怎么做某一类事** |
|
|
| `workflows/` | 元流程(如何承接→分析→评审→执行→验证→沉淀一个任务) | **如何承接任务** |
|
|
|
|
通用顺序:**先 knowledge 对齐事实 → 看 rules 划红线(且红线有机械门禁兜底)→ 用 skills 落地 → 按 workflows 推进与收尾。**
|
|
|
|
---
|
|
|
|
## 二、文件清单(✅ 已建 / ⏳ 建设中)
|
|
|
|
**rules/**
|
|
|
|
| 文件 | 状态 | 一句话 |
|
|
|---|---|---|
|
|
| [`rules/verification-and-anti-false-green.md`](rules/verification-and-anti-false-green.md) | ✅ | **脊柱规则**:完成=机械验证、机械门禁优先、反假绿(P0 已落地首批门禁) |
|
|
| [`rules/bc-boundaries.md`](rules/bc-boundaries.md) | ✅ | BC 边界:禁跨域 .dal 直连,ArchUnit 机械约束(已知违例 ContentMuseWorkOwnerFacade 单点登记整改) |
|
|
| [`rules/contract-first.md`](rules/contract-first.md) | ✅ | 契约先行:API=`docs/api-contracts/*`、DB=`sql/muse/V*` **原地 SSOT**;Flyway 卫生 + OpenAPI 结构 机械门禁(openapi-diff 已接 root workflow,远端首跑待确认) |
|
|
| [`rules/engineering-conventions.md`](rules/engineering-conventions.md) | ✅ | 工程约定:最小变更、契约协作、测试完成口径、CI/发布/回滚;已收敛 dev-baseline global 01-04 |
|
|
| [`rules/security-and-reliability.md`](rules/security-and-reliability.md) | ✅ | 安全可靠:可信边界、外部依赖 fail-closed、幂等补偿、日志审计;已收敛 dev-baseline global 05-06;含跨域物化特有红线(本地键不存外域 id、隔离靠物理副本非运行时过滤、前置未就绪 fail-closed) |
|
|
|
|
**knowledge/**
|
|
|
|
| 文件 | 状态 | 一句话 |
|
|
|---|---|---|
|
|
| [`knowledge/project-and-architecture.md`](knowledge/project-and-architecture.md) | ✅ | Muse 定位 / 意图 / 非目标、最高不变式、工程底座、7 BC 职责与约束(蒸馏 design-docs) |
|
|
| [`knowledge/module-reality-baseline.md`](knowledge/module-reality-baseline.md) | ✅ | 模块**真实**现状指针(指向现状基线 spec + 对抗复盘)+ 基建复利进展 |
|
|
| [`knowledge/tech-decisions.md`](knowledge/tech-decisions.md) | ✅ | 已确认架构决策蒸馏(指向 `架构-03-ADR` + CLAUDE.md 决策表) |
|
|
| [`knowledge/external-deps-and-gotchas.md`](knowledge/external-deps-and-gotchas.md) | ✅ | 外部依赖(New-API/RAGFlow 地址·凭据来源)+ 集成兼容坑 + 前端/构建坑(蒸馏自已清理 memorys) |
|
|
| [`knowledge/market-install-downstream-materialization.md`](knowledge/market-install-downstream-materialization.md) | ✅ | market 安装下游物化机制 + KB 类型 D0-fork 私有隔离(四单元闭环、进程内事件/跨 BC 读端口/kb_id 去污染;agent handoff 物化与 KB 召回阻断已闭环,副本回收等后置) |
|
|
|
|
**skills/**
|
|
|
|
| 文件 | 状态 | 一句话 |
|
|
|---|---|---|
|
|
| [`skills/golden-journey-vertical-slice.md`](skills/golden-journey-vertical-slice.md) | ✅ | "完成"的样板:三指标 + 关 mock(MSW dev-only)+ 真后端真库 + IT/Playwright 端到端 |
|
|
| [`skills/add-business-module.md`](skills/add-business-module.md) | ✅ | 新增 muse-module(BC)标准步骤:两子模块 + 契约 + 迁移 + 注册 + 守 BC 门禁 |
|
|
|
|
**workflows/**
|
|
|
|
| 文件 | 状态 | 一句话 |
|
|
|---|---|---|
|
|
| [`workflows/ai-development-protocol.md`](workflows/ai-development-protocol.md) | ✅ | 承接→分析→评审→执行→验证→沉淀;简单/全流程分流 + 证据门 + 构建纪律 |
|
|
|
|
---
|
|
|
|
## 三、维护规则(关键)
|
|
|
|
1. **何时新增 vs 更新**:全新主题→新增文件;已有主题补充/修正→更新现有文件(先查重,不造重复)。
|
|
2. **过时即处理**:信息失效立即修正或删除;与代码/文档冲突时以**已验证事实**为准。
|
|
3. **单一主题、精炼、可检索**:每文件聚焦一主题,多用表格;做蒸馏与索引,不照搬源文档大段内容。
|
|
4. **同步索引**:任何结构性变更(增/删/改名)同步更新本 README 清单 + [`../AGENTS.md`](../AGENTS.md) 导航。
|
|
5. **rules 必配门禁**:新增 rule 时必须说明其**机械门禁**落点(CI/ArchUnit/测试),否则它只是会被绕过的软约束(本项目教训)。
|
|
6. **语言**:一律简体中文;交叉引用用相对路径。
|
|
|
|
> 维护本身是任务收尾的一部分——见 [`workflows/ai-development-protocol.md`](workflows/ai-development-protocol.md) 的"沉淀"环节。
|