lili e181669197 chore(agent-infra): 建立 agent 开发基建、清理历史 churn 并以 BC 违例整改验证

本会话三部分交付,均经 JDK21 真实构建验证(非退出码,读 BUILD SUCCESS + Tests run):

1) Agent 开发基建(机械门禁优先)
- 入口与中枢:AGENTS.md、.agents/{knowledge,rules,skills,workflows}、CLAUDE.md 订正
- 订正 .gitignore:移除对 .agent/.agents 的忽略——它们是版本化 agent 基建,须入库(此前被忽略致克隆即缺)
- 机械门禁:CI 真跑测试(maven.yml JDK21、去 -Dmaven.test.skip)、覆盖台账去硬编码、
  BC 边界 ArchUnit 门(BcBoundaryArchTest)、契约先行门(ContractFirstGateTest:Flyway 卫生 + OpenAPI 结构)
- 单一进度源 docs/mvp/进度总账.md + 7 个 BC per-module .agent + mise.toml(锁 JDK21)
- P1 增量:AiSuggestionMergeProjectionFacade(Gap A)、ContentSourceServiceImpl 事务化 outbox 回流(Gap B)

2) 过期历史文档清理(97 份 churn,git 可恢复)
- 删 docs/memorys(34)、agent-specs 审阅/执行版+迁移review(34)、superpowers/plans+specs(25)、
  design-docs/临时+memorys(4);保留 superpowers/reports/coverage(门禁依赖)
- 唯一干货蒸馏入 .agents/knowledge/external-deps-and-gotchas.md;订正大纲/映射表/基线悬空引用

3) P1 harness 验证:消除已登记 BC 违例 ContentMuseWorkOwnerFacade
- content-api 新增只读端口 MuseContentWorkOwnerApi + content-server 实现(读自有 DAL);
  AI 适配器改消费该端口、移除全部 content.dal 依赖,AI 业务规则与 4 消费者不变
- 删除 ArchUnit 豁免 → 门禁收紧(反向红 31 例 / 正向绿;适配器单测 13/0F、端口实现 7/0F)

注:muse-studio/src(SSE 相关 4 文件)与 muse-module-ai/pom.xml(移除孤儿 contract-server)
为本会话之前已存在的未提交改动,非本次工作,未纳入本提交。

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

2026-06-14 04:38:07 -07:00

5.0 KiB

Raw Blame History

muse-design-docs 仓库 CLAUDE.md

仓库职责

muse-design-docs 是 Muse 四仓架构中的设计文档仓，承担产品、架构、流程、前端、后端、专题设计的 单一事实源（SSOT）。

不承载运行时代码
不承载 CI/CD 配置或部署脚本
只定义目标设计和 owner 归属
实现仓（muse-cloud / muse-admin / muse-studio）的代码、迁移和测试必须反向对齐本仓的正式文档

文档编写规范

文件命名

格式：{角色前缀}-{编号}-{主题}.md

角色前缀	适用范围	示例
产品	产品定位、功能边界、用户旅程	`产品-01-产品定位与核心价值.md`
架构	系统边界、数据模型、ADR、状态机	`架构-02-核心数据结构与双轨模型.md`
后端	领域模型、工程结构、Schema、API	`后端-04-统一数据库Schema-v1.md`
前端	工程结构、编辑器交互、动态表单	`前端-02-编辑器与影子层交互.md`
流程	操作流程、系统处理流程	`流程-01A-管理员操作流程(操作视角).md`
专题	跨领域专项设计	`专题-03-AI编排上下文与质量评测实现规范.md`

规则：

扁平结构，不建子目录（prototypes / memorys 除外）
编号连续，新增文档取当前最大编号 +1
子编号用大写字母后缀（如 02A、02B）
文件名即归属，避免目录层级变成垃圾桶

版本管理

每个文档头部必须包含：

- 版本：v{N}
- 更新日期：YYYY-MM-DD
- 目标读者：{角色列表}
- 阅读时间：{N}-{M} 分钟
- 边界说明：{本文件负责什么，不负责什么}

规则：

每次实质性修改（非 typo）必须递增版本号
更新日期使用 ISO 8601 格式
边界说明必须明确"负责"和"不负责"

交叉引用

只允许"链接 + 一句话摘要"，禁止大段复制粘贴
格式：详见 [文档名](文件名.md)：一句话说明该文档在此上下文中的作用
引用目标必须是正式文档，不引用临时文档作为长期依据
引用链接使用相对路径

术语统一

所有术语以 架构-02-核心数据结构与双轨模型.md 为权威定义
核心术语必须使用中文名（英文名）格式：规范数据(Canonical)、待审层(Shadow)、作品(Work)、章节(Chapter)、文本块(Block)、元结构定义(MetaSchema)
新术语必须先在 架构-02 中定义，再在其他文档中引用
禁止在非 owner 文档中创造新术语或给已有术语起别名

单一归属

每个概念只有一个 owner 文档，其他文档只能引用。归属清单见 内容映射表.md。

概念类型	Owner 文档
产品定位、功能边界	产品-01 / 产品-02
用户旅程、操作步骤	产品-03 / 流程-*
系统边界、BC 划分	架构-01
核心模型、双轨规则	架构-02
架构决策	架构-03
状态机、约束	架构-04
领域模型、聚合	后端-01
工程模块职责	后端-02
表结构	后端-04
API 契约	后端-05
编辑器交互	前端-02
动态表单	前端-03

Agent 行为约束

修改前检查

修改任何文档前，必须先读取 内容映射表.md 确认该概念的 owner
如果当前文档不是 owner，只能添加引用链接，不能重复定义
如果需要修改 owner 文档中的概念定义，必须在 owner 文档中修改

禁止行为

不在非 owner 文档中重复定义概念（即使措辞不同）
不大段复制其他文档内容
不创建与现有文档职责重叠的新文档
不用临时文档的内容反向覆盖正式分册
不在文档中硬编码实现细节（具体代码路径、类名等属于实现仓）

修改后验证

检查交叉引用完整性：被引用的文档和章节是否存在
检查术语一致性：新增或修改的术语是否与 架构-02 一致
检查版本号和更新日期是否已递增
检查边界说明是否仍然准确

新增 ADR 规范

新增架构决策记录（ADR）必须包含以下结构：

### ADR-{编号}：{决策标题}

- 状态：{proposed | accepted | deprecated | superseded}
- 日期：YYYY-MM-DD

#### 背景
为什么需要做这个决策？当前面临什么问题？

#### 选项
| 选项 | 优势 | 劣势 | 适用场景 |
|---|---|---|---|
| 选项 A | ... | ... | ... |
| 选项 B | ... | ... | ... |

#### 结论
选择了什么？为什么？

#### 后果
- 正面影响：...
- 负面影响：...
- 需要配套的变更：...

新增文档规范

新增文档前必须：

确认没有现有文档已覆盖该主题
确认新文档的 owner 边界不与现有文档冲突
在 00-文档大纲.md 和 内容映射表.md 中注册
使用标准头部模板

与实现仓的关系

本仓定义"应该是什么"，实现仓定义"如何做到"
实现仓发现设计文档有歧义或缺陷时，应提 issue 到本仓，而非自行解释
设计文档变更后，需评估对三个实现仓的影响并在 PR 描述中说明

5.0 KiB Raw Blame History Unescape Escape