games-development-ai/.agents

.agents/ —— 绘境AI 项目的 Agent 能力中枢

本目录沉淀并积累项目的全部 Agent 能力、技能与规则，让团队在长期开发中复利式积累知识、流程与能力，持续提升 AI 驱动开发的能力、准确率与稳定性。

工作入口、项目定位/目标/目录均见 ../AGENTS.md（项目唯一入口）；CLAUDE.md 仅以 @AGENTS.md 导入它。

---

一、本目录是什么

随着项目长期、跨会话推进，零散的认知和踩坑很容易丢失，AI 每次都"从零理解"。.agents/ 把这些沉淀成结构化、可检索、可复用的资产：事实蒸馏、硬约束、操作手册、元流程各归其位。每次任务从这里取经验、向这里存经验，能力随时间累积而非反复重置。

---

二、目录结构与职责

子目录	职责	回答的问题
knowledge/	事实与蓝图的蒸馏（产品、架构、范围、术语）	是什么
rules/	必须遵守的硬约束（工程规范、安全可靠性）	必须怎样
skills/	可复用操作手册 playbook（怎么做某一类事）	怎么做
workflows/	元流程（如何承接、推进、收尾一个任务）	如何承接任务

完整文件清单

knowledge/

文件	一句话说明
knowledge/product-and-architecture.md	产品定位、13 模块与依赖、三仓三端架构蒸馏
knowledge/tech-decisions.md	技术栈与关键选型理由
knowledge/mvp-scope-and-milestones.md	MVP 的 55 项 P0 产品功能范围、里程碑与验收指标

rules/

文件	一句话说明
rules/engineering-conventions.md	命名/分层/API 路径/错误码/提交/PR 等工程规范
rules/security-and-reliability.md	安全基线、幂等、超时重试、合规与可靠性约束（§1 含「@PermitAll 公开读端点纪律」三条：裁字段/DataPermission/租户 scoping，P-OPN-08 实证；§4 含「外部 IO 一律不入 DB 事务」泛化红线 + §4.1 资金打款特例）
rules/build-vs-buy.md	自研偏误防线(R1-R7):现货尽调前置门/形态终点测试/约束血统/prior-art 强制步/名义采用禁令/抽象墙审计

skills/

文件	一句话说明
skills/add-business-module.md	新增一个 game-module 业务模块的标准步骤
skills/add-game-template.md	新玩法模板接入配方（契约→prompt→runtime→后端→编排器→五级验收门，merge 实战收口版）
skills/littlejs-game-dev.md	AI 直接写 LittleJS 游戏代码作业手册(code 层)：12 插件 API 速查(8 基元 + 4 编排=session-score/hud-ui/scene-fsm/timer-scheduler) + 可导航代码结构 + 写 WHAT 调 HOW 边界 + 资产/mmx 流 + 工厂五法契约 + 受控面铁律（终态产物=src/ 多文件工程，取代废弃的 gameDefinition JSON 投影线）
skills/sim-business-game-design.md	经营模拟小游戏玩法设计作业手册(给 SAA design 层)：放置/经营/养成爆款范式(玩法/机制/进度/数值/美术/UI/音)→ 映射 A-model 12 插件可达子集 + design 层输出配方 + 反"无趣"8 条自检；与 littlejs-game-dev(code 层)配对
skills/runtime-and-multichannel.md	运行时打包、沙箱、SDK 与多渠道导出手册
skills/contract-first-development.md	契约先行：契约对齐与并行解耦
skills/prompt-governance.md	Prompt 即第 8 契约：Registry/加载注入/eval 门禁/HITL 治理手册
skills/wave-close-checklist.md	波次收口八步检查单——所有收口铁律指向的唯一可执行清单（第 8 步=spec 退役/分层 + docs/agent-specs/_index.md 维护）
skills/staging-ops.md	staging 运维配方：机器分工/代码同步/后端重部署/前端构建门/冒烟门
skills/ui-walkthrough-cdp.md	真 UI 走查配方（CDP on mini-desktop）：studio/admin 走查 + CDP 七坑 + 信道探针
skills/game-e2e-cdp-harness.md	Canvas 游戏 e2e 证据 harness：编排形制/驱动器六律/出厂红线/四件套口径（T1b-α 实证；§7 = W-G1 生成游戏真玩九门 = 假绿守卫 G 门 + H 机制/latch + I 控制手感 + 自产 gatespec）
skills/cheap-model-game-generation.md	便宜模型（new-api DeepSeek/MiniMax）直出可真玩轻游戏 L1 worker：链路/模型与成本/L1 纪律/坑红线/latch 套壳/design agent 自产 gatespec/质量三层（W-G1 HJ-GEN-001 实证）。注（2026-06-26）：reframe 后便宜档生成已迁 cheap-worker/（Python/AgentScope，见 agentscope-2.0-facts 实现速查 + memory amodel-generation-build-state）；本条 W-G1 gamedef/factory/worker-loop 路已退役，仅成本/代理坑/模型画像/质量三层跨路有效（详见篇首状态注）
skills/agentic-amodel-generation.md	agentic A-model 生成 harness（ReAct+M3 已实证·生产形态）：scaffold→工具循环（read/write/list/check/build/done）→循环外 play；链路/5 文件/运行配方/8 坑（write 前缀·compaction·停机纪律·防假绿·bundle.tick·boot envelope·路径深度）/M3 3-玩法自闭环实证/主流定性；取代旧 gamedef 单次产线（HJ-AGI-003）
skills/gen-path-parity-harness.md	两条生成路对照验证(parity) harness 范式 + 按品类 ≥80% 达标门 + auto-vs-golden 同款双驱动 delta 门：验「换实现后生成质量没回退」(Node→Python 重写/换模型/换框架)+ 判「生成质量够不够格上线」+ 判「生产自动 spec 比金标有没有驱动退化」(Node 退役授权)。对照公平铁律=驱动器 held constant(每品类金标 play-spec 喂两路)/ 金标只对 tap-targets 族公平(key-cycle 按键是生成侧自由选择不在 forensics 契约,需输入键契约)/ 注入=生成与 play 拆步+金标覆写 staged 真路径(非 evidence)/ 两层判据+逐品类绝对地板+双低标红(防 flaky 基线假等价)/ 成功定义钉死「金标 spec 下」≠生产许可/ 自动 spec 期望外生防自证(语义期望字段不从被测实际反推)/ 达标门质量口径(编排未收敛 timeout/step_cap 剔出达标率分母、单列归编排硬化,rawPassRate 并报贴近生产交付率)/ auto-vs-golden 门(同款 play 两次只换驱动器、关键门容差 0 单边查「自动不比金标驱得差」、retire 三条齐 M1∧002∧auto-vs-golden;实证抓到单数 target vs 复数 targets 生成契约漂移)/ 端口池+线程前台有界并发；WU-A 后续 compare_node.py、M1 达标门(003 bake_off.py)、M2 auto-vs-golden(2026-06-27-001 auto_vs_golden.py)实证(均过双评审);M3b 9d trace/D11/D9 parity(换 worker 别静默退化 D11:必填七项 + gatespec.driver 键名坑 + H_progress 嵌套 + repairs=max(0,attempts-1);退化判别=双峰 45/55、逐维断言反假绿非看区间;import 边界 tier2≠wg1 故 trace 手写镜像 + dedup vendor;真后端三值 28/45/100 实证)
skills/saa-graph-orchestration.md	SAA（Spring AI Alibaba）裸 StateGraph 生成编排：拓扑/加节点/接 new-api(剥 /v1 坑)/checkpoint(含 saved_at 无 tiebreaker 框架坑+显式 checkPointId 修法)/observation/最小依赖集/派发契约/验证门（HJ-AGI-002 实证）
skills/tier2-service-generation.md	tier2 富游戏服务态生成驱动配方(create_app :8200 + 控制面有界 resume)：★收敛头号杠杆=真玩 driver(没 driver→F_wiring 挂+富游戏门 None+agent thrash 假性不收敛;默认 business-sim play_spec 通用修复·007 现成游戏带 driver 重跑 accept 全绿坐实) + 驱动 create_app 六口径(凭据 data 嵌套/chat content 块列表/Toolkit.tool_groups 抠九工具/BYPASS+query agent_id/设计阶段接入/SSE read 超时防挂死) + 控制面 resume + C1 trace 字段口径(2026-06-24 服务化实测)
skills/doc-organizer.md	文档整理助手（创始人手动触发）：增量(上次清理→现在)+两阶段审批门——发起分析 Workflow→编清理计划→评审→批准后才执行；三轴=过期档清理(归档/压缩)/核心设计档措辞对齐现行真相/主任务总账回填；底层 tools/doc-organizer.{sh,-analyze.mjs,-state.json}（检测自动·判断留人·脚本不自删·最新日在飞档不碰）
skills/drive-remote-claude-tmux.md	远程驱动交互式 Claude Code（ssh + tmux）：双向通道 send-keys 派活 + capture-pane 读屏，不走 ACP/headless；每设备配置块 + onboarding 侦察配方 + 专用会话(独立 worktree 防撞树) + bypass-perms + 安全红线；完成判据=git push 非读屏（创始人 2026-06-18 拍板·多设备复用）
skills/architecture-diagram-atlas.md	架构图集生成配方：house style 规格 / 图说文档结构(金样板) / 三范式纪律(单源·防漂移门·状态双层) / 按域并行编排(克隆金样板·结构化返回) / 复验脚本 / 双评审揪出的六坑(漏域·现行远期错标·缺状态列·契约画理想·凑数配额·复制Mermaid漂移) / 分两期+跨session协调(生成引擎子树归在飞线只链不画)（2026-06-22 第一期实证）
skills/feature-design-doc.md	功能设计文档作业手册：取代 agent-specs review/execution 双档；一份文档 WHAT(意图/目标/边界/验证)+HOW(方案/步骤)合一；一式两份(文字+Mermaid 给人/AI · SVG/HTML 给人更重要、看图即懂)；复用 atlas house style + 防漂移单源(文字为准) + 媒介分工(md 直渲 Mermaid/SVG · HTML 链接打开)（2026-06-24 创始人定）
skills/execution-plan-slicing.md	执行 plan 切分轴：横切关注面 vs 纵切成果切片：多单元 plan 按成果纵切(每片自带全部关注面、做完不回头)而非按关注面横切(目标与手段分散→返工)；诊断信号="每到下阶段前面要重做"+依赖≠返工；换轴=横切降为"单元→切片"设计面对账(不删不新建、canonical 唯一性门原地重构、文件名留)+执行按切片走；三层文档(设计SoT→执行序列SoT→切片细化)；设计HOW移交设计SoT vs 执行契约(迁移/灰度/回滚/幂等)必须留切片的判据；必查五坑=过时口径搬成假前置门/对账漏面/元叙述/评审状态漂移/执行契约被当设计细节压掉(2026-06-26 plan① 换轴实证)

workflows/

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

---

三、使用方式（按任务类型查阅）

任务类型	先读	再读
分析	workflows/ai-development-protocol.md + 相关 knowledge/	原始 docs/architecture/ 长文档
评审	rules/（拿约束当尺子） + knowledge/	对应 skills/ 看实践标准
编码	对应 skills/（操作手册） + rules/engineering-conventions.md	knowledge/ 对齐上下文
调试	相关 skills/ + knowledge/	rules/security-and-reliability.md（排查可靠性/幂等问题）

通用顺序：先 knowledge 对齐事实 → 看 rules 划红线 → 用 skills 落地 → 按 workflows 推进与收尾。

---

四、维护规则（关键）

.agents/ 的价值取决于是否被持续、规范地维护。务必遵守：

1. 何时新增 vs 更新现有
   • 出现全新主题（新模块手册、新流程）→ 新增文件。
   • 是对已有主题的补充/修正→ 更新现有文件，不要另起炉灶造重复。
2. 先查重：新增前先检索本目录，避免重复条目和同义文件。
3. 过时即处理：信息失效时立即修正或删除，不留误导性内容；与代码/文档冲突时以已验证事实为准。
4. 单一主题、精炼、可检索：每个文件聚焦一个主题，用表格与要点，便于 Agent 快速定位；避免照搬源文档大段内容，做蒸馏与索引。
5. 同步索引与交叉链接：任何对 .agents/ 的结构性变更（增/删/改名文件），都要同步更新本 README 的清单，以及 ../AGENTS.md 中相关导航与交叉链接，保持全局一致。
6. 语言：一律使用简体中文。
7. 相对路径链接：文件间交叉引用使用相对路径，保证仓库迁移后链接不失效。

维护本身就是任务收尾的一部分——见 workflows/ai-development-protocol.md 的"沉淀"环节。