| title | AI协作规则 |
|---|---|
| type | rule |
| status | active |
本文件是项目级 AI 协作规则入口。
它约束的重点只有五件事：
- 如何开始一个任务
- 什么时候必须先出方案
- 什么时候可以直接执行
- 完成后最少要验证到什么程度
- 哪些信息必须沉淀到文档
本文件应保持稳定、简洁、可执行。不要把临时任务细节写进这里。
EngineSkill 是项目根据实际引擎约定的技能集合占位符。初始化时根据项目类型确定具体引擎：
- Unity 项目：使用 Unity 相关技能（场景对象、脚本、编译反馈）
- Godot 项目：使用 Godot 相关技能（节点、GDScript、场景）
- Unreal 项目：使用 Unreal 相关技能（蓝图、C++、关卡）
- Web/其他：使用对应技术栈技能
凡是与引擎编辑器相关的操作，优先使用对应的 EngineSkill，不允许直接凭记忆或手工操作。
MySuperPowers 是本地定义的流程增强技能挂件，放在 MySkills/ 目录下。
它只负责补强方案、计划、调试、验证等过程，不替代本文件的权威规则。
MyDocsSkill 是本地定义的文档技能包，放在 MySkills/ 目录下。
它只负责 Docs/ 初始化、文档增强层，不替代本文件的权威规则。
迭代 是当前任务下一个可交付、可验证、可记录、可等待用户确认的小闭环。
默认一次只允许推进一个迭代目标。
步骤 是为完成当前迭代而执行的内部动作。
一个迭代可以拆成多个步骤，但这些步骤只能服务于当前迭代，不得借机推进到下一个迭代。
AI 首次接手任务时，按以下顺序行动。
- 检查是否有Skill使用规则文件，根据文件要求使用Skill
- 如项目存在
MySkills/本地技能目录，优先检查并使用与当前任务匹配的本地技能 - 优先阅读
MySkills/README.md，再进入具体本地技能目录 - 技能规则源以
MySkills/为准，不维护.claude/skills/规则镜像 - 涉及
Docs/初始化或 Obsidian 文档增强时，优先检查并使用MyDocsSkill - 涉及子智能体并行编排时，优先检查并使用
ParallelSkills - 涉及行业规范、项目命名约定、模块规则或专项技能草稿接线时，优先检查
workflow/constraints与MySkills/project-constraints/README.md - 本地技能不得绕过本项目
Docs/文档体系，不得创建或使用外部默认文档根目录，除非用户明确要求
在任何涉及审查、分析、执行或子智能体 spawn 的任务前，必须先读取 Docs/Current/project-fingerprint.md：
- 确认本文件的项目根目录字段与当前工作目录一致
- 输出确认信息：
✓ 当前项目：CrossGate 复刻（D:\BaiduNetdiskDownload\TwMlBB） - 如路径不匹配或文件不存在，立即停止并提示用户确认工作目录
- 此项对审查类任务（team-review、parallel-analyze）为强制前置
此规则解决"子智能体/审查角色引用旧项目上下文"的问题。
至少确认以下信息：
- 本轮是分析、方案、执行、评审，还是仅建议
- 本轮目标是什么
- 是否允许直接落地修改
- 是否存在时间优先或稳定性优先约束
如果用户只是提出需求，而以下信息仍不明确：
- 目标边界
- 成功标准
- 是否要先看方案
- 是否允许直接开始改动
则 AI 必须先提问或先用一小段话复述理解并等待确认，不能直接进入方案阶段。
按“与任务成比例”的方式理解项目，不要求每轮都全量阅读。
- 小任务：只读必要代码和最近相关文档
- 中任务：补读当前阶段、相关计划、相关日志和模块边界
- 大任务：系统阅读当前阶段、架构规则、模块索引、最近计划与日志
如果项目尚未具备最小 Docs/ 骨架，而本轮任务已经需要计划、阶段信息或迭代沉淀，AI 应自动创建最小文档结构，不要求用户手动创建目录或复制模板。
如果项目同时启用了文档系统增强补充文件，自动初始化时应一并创建该增强层要求的最小文档节点。
禁止在证据不足时做结构性判断。
- 如果本次对话用户已经明确设定了任务级别（S/M/L），则 AI 应直接按照该级别的默认动作执行，无需再进行分析判断。
特征：
- 小范围修复
- 单文件或少量文件调整
- 不引入新的关键技术决策
默认动作：
- 可以直接执行
- 但执行前仍要说明理解和做法
- 若 S 级任务形成了可交付、可验证的执行闭环，完成后默认也补一条最小独立迭代日志文件；纯分析、纯建议或未形成执行闭环的 S 级任务可不单独写日志
- 默认不要求单独写计划文档
特征：
- 跨 2 到 5 个文件
- 有明确行为变更
- 可能影响已有模块协作
默认动作：
- 先给最小方案与整体迭代计划
- 用户确认计划后执行
- 每个已完成迭代都必须在
Docs/IterationLogs/下新增独立迭代日志文件 - 每个迭代完成并记录后等待用户确认，再进入下一迭代
特征：
- 跨模块
- 涉及边界调整、目录迁移、架构收口、基础设施扩展
- 验证成本高或回退成本高
默认动作：
- 进行头脑风暴考虑多种方案
- 将方案的功能点拆分开提问用户最终形成完整方案，用户确认后把最终方案写到计划文档里
- 每个功能点方案给用户至少3种成熟选择；每个选项都必须写清适用前提、核心改动、优点、风险或成本、验证影响，并给出一个推荐方案与推荐理由
- 计划文档必须先写出整体迭代总览、各迭代目标与推荐推进方向，且计划文件名必须带
YYYY-MM-DD-年月日前缀，再等待用户确认 - 总方案必须分迭代执行，每个迭代都按照文档系统要求写迭代文档
- 当前迭代可以拆解成多个步骤执行，但这些步骤只能服务于当前迭代
- 必须明确范围、风险、非目标、验证方式
- 每个迭代完成后提示用户测试，并在
Docs/IterationLogs/下新增该迭代的独立日志文件 - 完成后同步更新相关文档
- 理解用户意图
- 建立最小必要上下文
- 识别边界、重复逻辑、耦合和潜在回归点
只有在以下任一条件满足时，AI 才进入方案阶段：
- 用户明确要求“给方案”
- 任务已被判定为 M 级或 L 级，且关键约束已确认
- AI 已完成必要追问，并得到用户确认
方案至少应覆盖：
- 目标
- 范围
- 涉及模块或文件
- 风险点
- 验证方式
- 非目标
若当前阶段在做头脑风暴或方案比选，则每个关键分歧点的输出至少还应覆盖：
- 至少 3 个彼此有真实取舍差异的选项；若客观上只有 2 个合理方向，必须说明为什么
- 每个选项的适用前提
- 每个选项的核心改动点
- 每个选项的主要收益
- 每个选项的风险、复杂度或实施成本
- 每个选项对验证、回退或后续扩展的影响
- 推荐方案与推荐理由
- 当前仍缺失的证据、假设或需要用户确认的点
若进入计划阶段，计划文档至少还应覆盖：
- 整体迭代总览
- 每个计划迭代的目标与顺序
- 推荐推进方向或推荐方案
- 当前不执行的迭代边界
若计划属于跨模块计划，则推荐在计划成稿前先经过 architecture-review 角度预审；该预审可复用 team-review 中的 architecture-review 角色，但不要求在计划阶段同时运行完整 team-review。
计划文档写入 Docs/Plans/ 时，文件名必须带 YYYY-MM-DD- 年月日前缀，推荐使用 YYYY-MM-DD-主题.md 或 YYYY-MM-DD-计划-主题.md。
计划文档完成后，AI 必须停止在“等待用户确认计划”这个节点；未获确认不得自动开始第一次迭代。
- 一次只允许推进一个迭代目标
- 一个迭代可以拆成多个步骤，但步骤只能服务于当前迭代
- 未获用户对计划的确认前，不得开始第一次迭代
- 当前迭代完成后，必须先完成验证
- M 级和 L 级任务在当前迭代完成后，必须先在
Docs/IterationLogs/下补独立迭代日志文件，且文件名必须带YYYY-MM-DD-年月日前缀 - S 级任务若形成了可交付、可验证的执行闭环，也应补一条最小独立日志文件；纯分析、纯建议类 S 级任务可不写
- 当前迭代完成并记录后，必须提示用户确认；未获确认不得进入下一迭代
- 尽量按小闭环推进
- 不在未确认的情况下进行高风险扩张
- 不为未来假设提前引入抽象
M 级和 L 级任务在当前迭代完成后，默认进入 team-review 审查流程。
M 级任务：默认运行 code-review + design-review 两轮。仅当改动涉及跨模块、目录迁移或新基础设施时，追加 architecture-review。
L 级任务：运行完整三轮（code-review + design-review + architecture-review）。
触发、模式选择、角色注入、专项约束装载与宿主降级路径，统一以 MySkills/parallel/team-review/SKILL.md 与 MySkills/parallel/README.md 为准。
机器可读配置源仍为 Docs/Current/session-active.md 中的 REVIEW-CONFIG 配置块。
不允许用“理论上可用”交付。
至少要给出以下之一：
- 编译或静态检查结果
- 测试结果
- 运行态验证结果
- 明确说明未能验证的部分与原因
只沉淀高价值信息：
- 新边界
- 新入口
- 新计划
- 已完成迭代的事实结果
当多份文档冲突时，按以下顺序判断：
AGENTS.mdDocs/Architecture/Docs/Current/Docs/Plans/Docs/IterationLogs/Docs/README.md
中大型任务完成后，至少检查：
Docs/Current/是否仍然一致- 首页导航是否仍然正确
- 新计划或日志是否有入口
- 是否存在旧项目路径、失效链接或模板缺失
如果上述检查发现项目缺少必要目录或基础文档，应由 AI 在本轮内补齐最小骨架，而不是把目录搭建转交给用户手工处理。
- 小改动：通常只补迭代日志，不改架构文档
- 中改动：每个已完成迭代都应补
Docs/IterationLogs/下的独立迭代日志文件，必要时更新相关模块文档与当前阶段信息 - 架构级改动：每个已完成迭代都应补
Docs/IterationLogs/下的独立迭代日志文件，并同步更新架构文档、当前阶段和索引
文档按认知价值更新，不按改动文件数量更新。
防止 Docs/Plans/ 和 Docs/IterationLogs/ 无限堆积，在以下任一触发条件满足时执行归档：
| 触发条件 | 归档动作 |
|---|---|
| 阶段切换（如 Sprint 0 → Sprint 1） | 归档上阶段所有计划和日志 |
| 计划全部迭代执行完毕 | 归档该计划和关联的全部迭代日志 |
Docs/IterationLogs/ 条目 ≥ 10 |
归档最早的 5 条日志 |
| 计划被废弃或替换 | 归档被废弃的计划到 Docs/Archive/Plans/ |
归档目录结构：
Docs/Archive/
├── README.md ← 归档总索引（必维护）
├── Plans/
│ └── README.md ← 已归档计划索引
├── IterationLogs/
│ └── README.md ← 已归档迭代日志索引
└── Current/
└── README.md ← 历史阶段存档（阶段切换时写入）
归档索引必须记录： 归档时间、原始路径、归档原因、关联文档或迭代。
归档后清理： 归档完成后从原目录删除文件，并更新 Docs/README.md 导航。
禁止项：
- 禁止归档当前阶段的计划和日志
- 禁止归档后不更新索引
- 禁止归档时不检查关联文档引用（避免断链）
不同任务复杂度应使用不同模型，以平衡质量与成本：
| 模型 | 适用场景 | 示例 |
|---|---|---|
| Haiku | 只读状态检查、格式化、简单查找 | 查询 Docs/Current/session-active.md、扫描文件列表 |
| Sonnet | 实现、设计撰写、单系统分析 | 默认模型；代码编写、模块设计、调试 |
| Opus | 多文档综合、高风险决策、跨系统审查 | 架构方案、L 级任务计划、跨模块重构、核心设计文档变更 |
约定：
- 若任务涉及 ≥3 个模块或需要综合 ≥5 份文档，使用 Opus
- 若任务仅需读取和汇报状态，使用 Haiku
- 其余默认使用 Sonnet
以下情况可优先使用 MySkills/parallel/：
- 任务需要跨多个不相关文件调查，预计消耗 >5k tokens
- 需要多维度并行审查（代码/设计/架构）
- 需要与主任务上下文隔离，避免污染主会话
- 3 个以上互不依赖的模块可并行分析或实现
- 审查与分析子智能体默认只读；bootstrap 子智能体只返回方案与建议；日常并行实现仅允许写入主智能体分配的文件
- 主智能体负责接口契约、文件分配、结果汇总、验证与最终写入
- 若任一子智能体被 BLOCKED，主智能体必须立即停止并报告用户
- 并行编排、双模式降级、审查范围、角色映射等动作协议，以
MySkills/parallel/README.md与对应技能SKILL.md为准 - 自定义角色定义统一从
MySkills/agents/读取；回退到默认描述时禁止静默 - 专项约束统一由主智能体从
MySkills/project-constraints/README.md匹配并注入；子智能体不得自行扫描约束目录
- 优先并行；宿主能力不足时按技能定义降级为顺序执行，不得伪装成已 spawn 的并行流程
- 子智能体 prompt 应保持“静态规则前置、动态上下文后置”，以提高前缀缓存命中率
- 业务层依赖基础设施层
- 基础设施层不能反向依赖业务层
- 通用框架不承载业务语义
- 同一对象内优先直接调用
- 同一系统内优先事件或明确回调
- 跨系统通信才使用消息中心
- 禁止当前迭代完成后未让用户测试或确认就直接推进下一迭代
- 计划文档刚写完就自动开始第一次迭代
- 未完成当前迭代日志就进入下一迭代
- 未获用户确认就连续推进多个迭代
- 禁止只在计划文件、当前重点或其他文档里补一句“第几个迭代已执行”来替代独立迭代日志
- 禁止计划文件或迭代日志文件缺少
YYYY-MM-DD-年月日前缀 - 禁止计划文档只写当前迭代，不给出整体迭代总览与推荐推进方向
- 未理解任务就直接改动
- 用户只提出需求、尚未确认关键约束时，AI 直接替用户制定完整方案
- 未确认就进行高风险重构
- 把业务语义塞进通用层
- 跳过验证直接宣称完成
- 为了“文档完整”频繁重写大段低价值文档
- 把过渡方案误当成长期架构
- 在没有明确授权时执行破坏性 Git 操作
一轮任务只有同时满足以下条件才算完成：
- 目标已交付或阻塞点已说明
- 变更范围已收口
- 验证结果已说明
- 需要时
Docs/IterationLogs/下的独立迭代日志文件已补齐 - 必要文档已补齐
- 给出了下一步入口或明确无需继续
以下规范按语义适用，不绑定具体路径。AI 在审查代码时，根据改动的文件内容判断是否适用。
- 核心游戏机制（移动、战斗、交互、判定等）必须是确定性计算，禁止使用随机数影响核心玩法结果
- 状态变更必须通过明确的规则系统，禁止硬编码魔法数
- 状态对象不得被原地修改（无副作用原则），变更必须通过显式方法或副本替换
- 搜索/决策算法必须有显式的性能预算（深度、宽度、时间限制）
- 状态评估函数必须保持对称性：交换双方视角应得到相反或可比较的分数
- 状态拷贝必须使用高效的手动拷贝，禁止在热路径使用 JSON 序列化/反序列化
- 新增算法前必须说明时间复杂度，禁止引入无剪枝的指数级搜索
- 渲染层只读游戏状态，不得反向修改业务逻辑状态
- 渲染分层必须有明确的深度/层级约定，禁止越层访问
- 渲染更新必须完整清除并重绘动态层，禁止增量更新导致残影
- 公共 API 必须有文档注释（
/// <summary>或等效格式） - 跨模块调用优先使用事件/回调/接口，避免直接引用具体实现类
- 业务层依赖基础设施层，基础设施层不得反向依赖业务层
- 通用工具代码不得承载业务语义