zizi-al/oh-my-muse
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
oh-my-muse/.agents/workflows/ai-development-protocol.md
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

3.6 KiB
Raw Blame History

workflow:AI 开发协议(承接→分析→评审→执行→验证→沉淀)

类型:元流程(workflows) · 简版规约:../../AGENTS.md §5 工作协议(本文件是其操作化展开)。 何时用:承接任何 oh-my-muse 任务时先走本流程分流。核心立场:机械门禁优先、完成=验证、反假绿。

〇、分流(先判复杂度)

路径 判据 流程
直通 简单 / 低危 / 局部 / 可清晰验证 目标 → 最小改动 → 验证 → 报告
全流程 复杂 / 高危 / 跨模块 / 改用户可见行为 / 触外部服务·支付·数据·模型 一~六全程

一、承接

二、分析

  • 第一性原理 + 金字塔:问题、边界、假设、风险、推荐路径。
  • 区分已验证事实 / 推断 / 假设;只读可得的先查代码·文档·配置·测试·日志,再问人。

三、评审(仅全流程)

  • 评审版 spec:docs/agent-specs/YYYY-MM-DD-主题-review.md(结论先行,只留背景/目标/非目标/推荐方案/权衡/影响面/风险/验收/待确认)→ 两轮评审 → 执行版 ...-execution.md(目标边界/前置/涉及文件/数据流/契约/步骤/失败路径/验证法/完成条件/回滚)。

四、执行

  • 最小改动:只动相关代码,复用既有模式,不顺手重构。
  • 无孤儿/拼接:任何新结构/接口/模型须带入口、使用路径、失败路径、验收标准。
  • 全简体中文注释;外部交互/核心实现/错误路径留可追溯日志。
  • 契约先行(见 ../rules/contract-first.md);守 BC 边界(见 ../rules/bc-boundaries.md)。

五、验证(证据门 —— 不可跳过)

  • 完成 = 机械验证;无自动化绿证据不得声称“完成/修复/通过”(见 ../rules/verification-and-anti-false-green.md)。
  • 用户可见功能按 ../skills/golden-journey-vertical-slice.md 的三指标报告(代码 / 自动化验证 / 端到端可用),不给单一百分比。
  • 关键门禁须绿:BC(BcBoundaryArchTest)、契约(ContractFirstGateTest)、CI 真跑测试(JDK21)。
  • 构建纪律(实证教训):① 勿并发跑多个 mvn 写同一 target(会致 NoSuchFileException 假错);② 勿信退出码 / 末尾 grep 掩盖——读 BUILD SUCCESS + Tests run / Failures 真实行;③ JDK21 经 mise exec 锁定。

六、沉淀(复利来源 —— 也是硬约束)

  • 把可复用产出回写 ../ 对应层:新事实→knowledge/;新硬约束(必配机械门禁)→rules/;新操作手册→skills/;流程改进→本 workflows/。
  • 先查重再新增;过时即修正/删除;结构性变更同步 ../README.md 与 ../../AGENTS.md 索引。
  • 进度进总账 + per-module .agent(建设中),不再新增“状态推进”过程文档(churn 是失控来源之一)。
  • 交付后按需询问:是否将关键信息持久化到 docs/memorys/ 或 docs/agent-specs/。

一句话:先对齐事实、划红线,再动手;动手必最小、必留证据;完成必机械验证、必沉淀。