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

6.4 KiB

Raw Blame History

AGENTS.md —— oh-my-muse(Muse)· Agent 工作入口

本项目以 AI 驱动开发。 无论你是 AI agent 还是工程师,每个任务都从这里开始。本文件是项目唯一事实源:既答"这是什么项目"(定位/目录),也答"怎么在这里干活"(先读什么、守什么规则、怎么把经验沉淀回去)。能力细节在 .agents/;CLAUDE.md 是 design-docs(设计 SSOT)的写作规范,从属本文件。

1. 项目定位

Muse = AI 驱动的长篇创作工具(Shadow→Canonical 主权:AI 产出经"先审后入"才进入正式正文)。四仓协作,采用 monorepo 承载。

仓	技术栈	职责
muse-cloud	Java 21 + Spring Boot 3 + PostgreSQL + Yudao 框架	后端(9 业务域 muse-module-*)
muse-admin	Vue 3 + Vben Admin + TS	管理端前端
muse-studio	React + Vite + TS	用户端前端
design-docs / docs	Markdown + SQL	设计 SSOT / agent 规格与基建

业务域:account(member) / ai / content / knowledge / market / meta / events + 平台底座。

2. ⚠️ 仓库物理事实(2026-06-14 订正,对抗复盘 A1/R6)

本仓是 monorepo,物理承载实现代码,不是"纯设计文档仓"。

git ls-files muse-cloud = 4468 文件、无 .gitmodules → muse-cloud/、muse-admin/、muse-studio/ 三个实现仓代码就在本工作树里、被本仓版本控制;CI 在 muse-cloud/.github/workflows/。
因此:agent 可以也应当修改这些实现代码(遵循各自规范 + .agents/rules/)。此前"本仓不承载代码/CI"的描述与磁盘矛盾,会让 agent 误判改动边界、绕路产生文档 churn,已订正。
design-docs/、docs/ 是设计/规格 SSOT;实现代码须反向对齐其正式文档。

3. 目录导航

oh-my-muse/
├── AGENTS.md                # 本文件:项目入口(唯一事实源)
├── CLAUDE.md                # design-docs 写作规范(从属本文件)
├── .agents/                 # Agent 能力中枢(knowledge/rules/skills/workflows;见 .agents/README.md)
├── muse-cloud/ muse-admin/ muse-studio/   # 三实现仓代码(可改)
├── design-docs/             # 产品/架构/前后端/流程/专题 设计 SSOT + 内容映射表/大纲
└── docs/
    ├── agent-specs/         # 现状基线 + 对抗复盘 + P0 冻结令 + 六砖交付(过程 churn 已清理)
    ├── mvp/进度总账.md       # 进度单一事实源(+ 历史交付时间线)
    ├── api-contracts/       # 各域 OpenAPI = API 契约 SSOT(原地;见 .agents/rules/contract-first.md)
    ├── dev-baseline/        # 既有全局/各仓规范(待收敛进 .agents/rules)
    └── memorys/             # 已归档清理(见 README);进度改用 mvp/进度总账.md

4. 任务前必读

序	文档	作用
1	`.agents/rules/verification-and-anti-false-green.md`	脊柱规则:完成=机械验证、机械门禁优先、反假绿
2	`docs/agent-specs/2026-06-13-项目目标与模块现状基线.md`	项目目标 + 模块真实现状(避免重复探索)
3	`docs/agent-specs/2026-06-13-目标达成对抗复盘.md`	失控根因(假绿)与重定路径
4	`.agents/README.md`	能力中枢导航
5	design-docs(`00-文档大纲.md` 入口 + `架构-01/02`、`后端-01`)	设计事实

5. 工作协议(硬约束)

读后动手:复杂任务先读 .agents/ 与相关 docs/,对齐事实再开工。
机械门禁优先 / 完成=验证:遵守 verification-and-anti-false-green——无自动化绿证据不得声称完成;新规则必配机械门禁,不靠自觉。
复杂/高危先评审:跨模块 / 改用户可见行为 / 触外部服务·支付·数据 → 评审版 → 两轮评审 → 执行版,再写代码。
契约先行:改接口/数据结构先改契约(API=docs/api-contracts/*、DB=新增 sql/muse/V*.sql,均为原地 SSOT)再实现;遵守 contract-first,已有 Flyway 卫生 + OpenAPI 结构机械门禁(openapi-diff 待启用)。
最小改动 + 中文注释:只动相关代码,复用既有模式,不顺手重构;代码全简体中文注释,关键路径可追溯日志。
无孤儿/拼接设计:任何新结构/接口/模型须带入口、使用路径、失败路径、验收标准。
证据规则:区分已验证事实/推断/假设;无证据不声称"完成/修复/通过"。

6. 知识沉淀机制(也是硬约束 —— 复利的来源)

.agents/ 的价值在于复利:让"越往后开发越快越准"。因此:

每次有价值的交付后,把可复用产出回写对应层:新事实→knowledge/;新硬约束(必配门禁)→rules/;新操作手册→skills/;流程改进→workflows/。
先查重再新增;过时即修正/删除;结构性变更同步 .agents/README.md 索引与本文导航。
进度只进 总账 + per-module .agent,不再新增“状态推进”过程文档(过程文档 churn 是失控来源之一)。

无沉淀的任务是"一次性消耗";有沉淀,下一个同类任务在已有成果上更快更准地推进。

7. 当前基建建设状态(随建随更)

✅ 机械门禁地基:CI 真跑测试(JDK21)、门禁去硬编码、P0 冻结令(见脊柱规则"已落地")。
✅ 入口与中枢骨架:本文件 + .agents/README.md + 脊柱规则。
✅ BC 边界 ArchUnit 门(bc-boundaries):AI 不得直连他域 DAL,已验证绿。
✅ 契约先行机械门禁(contract-first):Flyway 迁移卫生 + OpenAPI 结构,原地 SSOT,已验证绿。
✅ knowledge 蒸馏 / skills(黄金旅程“完成”定义 + 加 BC 模块)/ workflow(AI 开发协议):见 .agents/README.md。
✅ 进度总账(单一进度源)+ 7 BC per-module .agent:见 docs/mvp/进度总账.md。
⏳ 后续(非阻塞):openapi-diff 破坏性变更 CI、docs/dev-baseline/global/* 收敛进 .agents/rules/(engineering-conventions / security-and-reliability)、BC 边界门扩到其它方向。

进度只进 docs/mvp/进度总账.md + 各模块 .agent,不新增状态过程文档。

6.4 KiB Raw Blame History