zizi-al/games-development-ai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
games-development-ai/AGENTS.md
zizi 570632793b docs: 品牌改名 绘境→造梦 / huijing→wanxiang(仅文档层)+ 治理文档更新 
- 品牌改名：中文 绘境→造梦、英文/拼音 huijing→wanxiang；严格仅文档/计划层
- 代码/契约/Java 根包名一律保持 huijing 不变(cn.huijing.game / HuijingGameSDK / contracts)
- 文档↔代码命名分叉为已知接受态，留待未来专门的后端包名重构(见记忆 brand-rename-huijing-to-zaomeng)
- .agents 治理体系 + CLAUDE/AGENTS 入口 + architecture 三文档套件 + memorys/superpowers spec 更新

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-08 09:11:10 +00:00

8.6 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。

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

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

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

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

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

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

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

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

六、gstack 工具集（全局技能）

gstack 是一套全局斜杠技能集（浏览 / 评审 / QA / 部署 / 文档 等），按开发者机器安装到 ~/.claude/skills/gstack，安装后下列技能即可在任意项目直接调用。

安装（每位成员各自执行一次）：

git clone --single-branch --depth 1 https://github.com/garrytan/gstack.git ~/.claude/skills/gstack \
  && cd ~/.claude/skills/gstack && ./setup

本项目硬约束：

  • 所有网页 / 浏览器操作一律走 gstack 的 /browse 技能：导航、抓取、页面巡检、QA 等任何 web 交互都用它。
  • 禁止使用 mcp__claude-in-chrome__* 工具：一律改用 /browse（或相应的 gstack 浏览技能）。

可用 gstack 技能：

/office-hours、/plan-ceo-review、/plan-eng-review、/plan-design-review、/design-consultation、/design-shotgun、/design-html、/review、/ship、/land-and-deploy、/canary、/benchmark、/browse、/connect-chrome、/qa、/qa-only、/design-review、/setup-browser-cookies、/setup-deploy、/setup-gbrain、/retro、/investigate、/document-release、/document-generate、/codex、/cso、/autoplan、/plan-devex-review、/devex-review、/careful、/freeze、/guard、/unfreeze、/gstack-upgrade、/learn

注：gstack 为开发者个人级工具，安装与个人偏好在各自 ~/.claude/ 配置；本节仅为团队成员在本项目内提供一致的使用入口与约束。