zizi 9735142518 docs: 文档治理——单一事实源去冲突 + 版本历史清理 + 文件名去日期

- 删除 4 个已过时文档（v2 架构选型审阅版 / v2 模块架构与MVP覆盖度 / 2 份已归档 review），
  架构文档收敛为 6 份、agent-specs 收敛为 1 份
- 消除冲突与陈旧值：基础设施成本 ¥3,800→¥4,300；生成成功率 85% 消歧为
  "远期蓝图 / MVP 验收 80%"；技术决策版架构图补 studio（12→13 模块）；
  契约口径全仓统一为 8 类（7 个 Day-0 contracts/ 文件 + Prompt Registry 第 8 类）
- 清理各文档内部历史/迁移/changelog 段落与失效引用（已删"业务能力全景"章节号引用、
  LayaAir 导出快手等事实错误）
- 8 个保留文档文件名去日期，全仓 markdown 链接与蒸馏来源引用联动更新；
  AGENTS.md 必读清单（7→5 份）与 CLAUDE.md 目录结构同步
- docs/memorys/ 按全局约定豁免（保留带日期归档），docs-design/ 不在本次范围

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

2026-06-07 17:46:17 +00:00

7.1 KiB

Raw Blame History

AGENTS.md — 绘境AI 项目 Agent 工作入口

本项目采用 AI 驱动开发。 无论你是 AI Agent 还是工程师，开始任何任务前都从这里进入。本文件回答"怎么在本项目里干活"：先读什么、去哪查、守什么规矩、如何把经验沉淀回来。项目"是什么/目标/目录"见 CLAUDE.md。

一、开始任何任务前的必读顺序

下面 5 份文档构成对项目的完整认知。首次接手或做架构级任务时按序通读；日常开发优先读 .agents/knowledge/ 下的蒸馏版，需要细节再回溯原始长文档。

顺序	文档	定位
1	`docs/architecture/系统概要设计-投资人版.md`	商业定位、资本效率、壁垒与窗口期
2	三文档套件：`docs/architecture/产品需求清单.md`(Doc A·产品WHAT) / `docs/architecture/技术架构与模块.md`(Doc B·技术HOW·13模块) / `docs/architecture/需求模块映射.md`(Doc C·RTM)	产品需求 / 技术模块 / M:N 映射（取代原"业务能力全景"）
3	`docs/architecture/系统概要设计-技术决策版.md`	技术决策全貌（架构基线）
4	`docs/architecture/系统概要设计-开发团队版.md`	日常开发手册：环境/目录/规范/联调/提交
5	`docs/superpowers/specs/mvp-execution-spec-design.md`	MVP 执行 spec：10 人×3 周、契约先行（验收=55 项 P0 产品功能 / 工作量≈137 技术项，正文已同步）

提示：原始文档很长，直接全读会拖慢任务。蒸馏版位于 .agents/knowledge/，是日常默认入口。

二、`.agents/` 目录导航

.agents/ 是项目的"Agent 能力中枢"，分四类。维护规则见 .agents/README.md。

knowledge/ —— 事实与蓝图蒸馏，回答"是什么"

文件	一句话说明
`.agents/knowledge/product-and-architecture.md`	产品定位、13 模块与依赖、三仓三端架构蒸馏
`.agents/knowledge/tech-decisions.md`	技术栈与关键选型理由（Yudao/Dify/OpenGame/自研Canvas+Cocos-MCP/Prompt 治理等）
`.agents/knowledge/mvp-scope-and-milestones.md`	MVP 的 55 项 P0 产品功能范围、里程碑与验收指标
`.agents/knowledge/glossary.md`	术语表（游戏流/GameConfig/Manifest/质量分等）

rules/ —— 硬约束，回答"必须怎样"

文件	一句话说明
`.agents/rules/engineering-conventions.md`	命名/分层/API 路径/错误码/提交/PR 等工程规范
`.agents/rules/security-and-reliability.md`	安全基线、幂等、超时重试、合规与可靠性约束

skills/ —— 可复用操作手册（playbook），回答"怎么做某类事"

文件	一句话说明
`.agents/skills/add-business-module.md`	新增一个 game-module 业务模块的标准步骤
`.agents/skills/ai-generation-pipeline.md`	AI 生成链路（Dify + OpenGame + aigc 壳）开发手册
`.agents/skills/runtime-and-multichannel.md`	运行时打包、沙箱、SDK 与多渠道导出手册
`.agents/skills/contract-first-development.md`	契约先行：API/DB/SDK/事件契约对齐与并行解耦

workflows/ —— 元流程，回答"如何承接一个任务"

文件	一句话说明
`.agents/workflows/ai-development-protocol.md`	任务承接→分析→评审→执行→验证→沉淀的完整协议
`.agents/workflows/mvp-execution-orchestration.md`	MVP 10-Agent×3周执行编排 + 8 条复利提效策略

三、工作协议（强约束）

以下为精炼条款，详细流程见 .agents/workflows/ai-development-protocol.md。

先读再动：遇到有真实复杂度的任务，先读 .agents/knowledge/ 与相关 docs/，对齐事实再动手。
复杂/高风险先评审：跨模块、改动用户可见行为、或涉及外部服务/支付/数据的任务，先出评审版 → 两轮评审 → 再执行，不要直接写代码。
证据规则：区分"已验证事实 / 推断 / 假设"。没有验证证据，不得声称"完成 / 已修复 / 通过 / 无问题"。 跑得了的（测试、构建、lint、冒烟）必须跑。
最小变更：只改与当前需求直接相关的代码，复用既有模式，不顺手重构无关命名/目录/格式。
中文注释：所有代码必须配完整简体中文注释；外部交互、核心实现、错误路径要有可追溯日志。
契约先行：接口/数据结构变更先更新契约（contracts/ 与 -api 包），再实现，并通知相关方。

四、沉淀机制（同样是强约束）

.agents/ 的目的，是让团队在长期开发中复利式积累能力，持续提升 AI 驱动开发的能力、准确率与稳定性。因此：

每完成一个有价值的任务，必须把可复用的产出回写到 .agents/ 对应目录：
- 新的事实/蓝图认知 → knowledge/
- 新的硬约束/踩坑红线 → rules/
- 新的可复用操作套路 → skills/
- 流程层面的改进 → workflows/
先查重再新增：能更新现有文件就不要新建；过时内容即时修正或删除。
变更 .agents/ 时，同步更新 .agents/README.md 的索引与相关交叉链接，保持导航一致。
一切内容用简体中文，保持单一主题、精炼、可快速检索。

不做沉淀的任务是"一次性消耗"；做了沉淀，下一次同类任务才能站在已有成果上更快更准。

五、效率原则（复利提效）

AI 驱动开发要"越做越快"——把每次产出沉淀为可复用资产，让效率随推进复利增长。8 条核心策略（详见 .agents/workflows/mvp-execution-orchestration.md）：

黄金模板先行：先把一个模块做到完美，其余克隆骨架。
契约先行：并行开发前必锁契约（API/DB/SDK/事件）。
复用优先于新建：写代码前先搜 skills/、knowledge/ 与既有代码，避免重复造轮子。
验证门禁前置：TDD + 门禁 + 完成前验证，早拦错、防返工（返工是头号效率杀手）。
并行边界 = 模块边界：Agent 间零共享状态、worktree 隔离、只经契约交互。
.agents 复利沉淀：每次交付回写经验（见第四节）。
昂贵步骤缓存：相同 Prompt hash 命中跳过 LLM；构建/产物缓存。
可复现编排：用 Workflow 脚本固化 fan-out + verify。

7.1 KiB Raw Blame History Unescape Escape