游戏开发博客

外观

引言 ​

《归义军传说》SRPG 和 BattleSystem-ECS 这两个个人项目，从 2025 年中开始到现在，大部分代码是和 AI 一起写出来的。两个项目加起来核心代码行数大约 7 万行（52K ECS Core + 17K Tests + SRPG ~40 个 C# 脚本）。这篇文章总结一下过程中积累的一些经验，主要面向"独立开发者 + AI 辅助"这个场景。

一、AI 适合什么、不适合什么 ​

经过这一年多的实践，我总结出 AI 最有效的几个场景：

适合的 ​

  1. 模板化/重复性代码：比如 BattleSystem-ECS 里 5 个 ComponentStore 的 partial class，结构一样但字段不同。让 AI 照一个写另外四个，基本零修改。

  2. 查阅文档 → 实现代码：做火焰纹章公式还原的时候，我把 FE7 的公式文档（Serenes Forest）链接給 AI，它读完就能写出符合规范的 CombatCalculator。从公式表格到 C# 代码，准确率很高。

  3. 单元测试生成：BattleSystem-ECS 有 1332 个 xUnit 测试，几乎全是 AI 写的。典型流程是：我写系统逻辑 → AI 生成覆盖 happy path + 边界 + 异常情况的测试用例 → 我 review 核心断言。

  4. 重构/迁移：把一个方法从 TowerAttackSystem 里提取出来放到 CombatCalculator，或者把 Dictionary 改为 HashSet[] SOA 数组，这种机械但容易出错的改动，AI 做得比我手动快且干净。

  5. 文档维护：设计文档、变更日志、架构图。让 AI 根据最新代码更新 docs/architecture.md 和 CHANGELOG.md，它不会遗漏改了哪些文件。

不适合的 ​

  1. 架构决策：AI 可以给你分析几种方案的优劣，但"要不要引入两阶段并行安全模式"这种决定必须自己判断。它在工程哲学层面的判断力不够——它可能给你一个"技术上更优雅"但"工程上过度设计"的方案。

  2. 性能瓶颈定位：AI 能优化它看到的代码，但它不知道哪一个操作是真正的瓶颈。Benchmark 之后发现 mode2 vs mode4 差距一倍这种事，需要自己跑数据、自己分析。

  3. 从零设计一个系统：不是说 AI 做不到，而是如果需求不够具体，它给出的方案通常是"教科书式的、正确但平庸的"。把设计文档写得足够详细（到字段级别），AI 的实现才会精准。

二、设计文档先行 ​

两个项目的一个共同点是——设计文档（Docs/）比代码写得早，也比代码写得详细。

《归义军传说》的设计文档有三个核心文件：

  • fire-emblem-mechanics.md：FE7 公式逐项对照，每项标注"本项目现状"和差距
  • combat-flow.md：战斗指令流程的状态机描述，精确到"右键取消 / 左键确认"的 UI 行为
  • battlefield.md：地形规则、范围显示、HD-2D 渲染分期方案

BattleSystem-ECS 的设计文档也不含糊：

  • architecture.md：系统架构图、组件存储结构、数据流、并行安全原则
  • philosophy.md：工程理念，从具体踩坑中提炼的设计原则
  • design-and-bugs.md：48 个 Bug 的追踪列表和修复状态

这些文档的作用不仅是给自己看的——它们是给 AI 看的。当你把一份详细到公式级别、字段级别、状态机级别的设计文档交给 AI，它产出的代码和你的预期偏差极小。如果只给一句话需求"帮我做个火焰纹章的战斗系统"，AI 的结果大概率需要大幅返工。

一个具体的经验：fire-emblem-mechanics.md 里有一章是"经验系统"，里面明确写了简化版公式：

伤害经验 = max(1, (31 + 敌Lv − 己Lv) / 3)
击破经验 = 伤害经验 + max(0, (敌Lv − 己Lv)×3 + 20)

并给了例子（Lv1 打 Lv1 = 30 EXP）。把这个文档給 AI 之后，它一次性写出了正确的 ExpGainUI.cs + BattleManager 里的经验结算逻辑，我不需要跟它反复解释"经验应该怎么算"。

三、AGENTS.md 和 CHANGELOG.md 的配合 ​

每个项目根目录都有一个 AGENTS.md——这是给 AI 看的"项目说明书"。它包含了：

  • 项目概述（一句话说清楚这是什么）
  • 技术栈和构建命令
  • 代码目录结构和模块职责
  • 修改规范（改什么的时候要注意什么）
  • 关键架构文件的索引

AGENTS.md 和常规 README 的区别在于——它是写给**完全不了解本项目的 AI（或新接手的人）**的，所以不能有"常识性省略"。比如"用 dotnet run 4 跑性能压测"，如果 README 可能只写"见 AGENTS.md"，但 AGENTS.md 必须写清楚命令参数和每种 mode 的含义。

同时，项目级的变更记录从 AGENTS.md 里剥离出来放在 CHANGELOG.md。AGENTS.md 保持稳定（项目约定不变），CHANGELOG.md 持续追加（每次会话做了什么、遇到什么坑、怎么解决的）。AGENTS.md 引用 CHANGELOG.md，新对话开始时 AI 先读两者建立上下文。

一个经常被忽略的细节：CHANGELOG 里不仅记"做了什么"，更要记"踩了什么坑"。比如归义军传说 CHANGELOG 里的这段：

- Main.unity 的 SceneSetup Missing Script：场景内 m_Script GUID 全为零（首个提交起即坏）
  改为 SceneSetup.cs.meta 真实 GUID cd60660c…
  验证：Windows 播放器构建成功，0 异常

记下来之后，下次如果换一个 AI 或者自己忘了，直接查 CHANGELOG 就知道"这个问题以前遇到过，修法是这样的"。

四、一些具体的协作技巧 ​

  1. 代码改动后让 AI 更新文档：每次改完代码，不要忘了让 AI 同步更新相关设计文档。docs/ 目录和代码不一致的话，下次对话 AI 会基于过时信息工作，返工率会大幅上升。

  2. 用 CHANGELOG 做会话交接：如果一次复杂的改动跨了多个 AI 会话，CHANGELOG 的条目是上下文交接的关键。把"当前进度、已完成/未完成、遇到的问题"都写进 CHANGELOG，下一个会话开始时 AI 直接读就行。

  3. 给 AI 看反例：跟 AI 说"不要这样做"有时不如给它看一个实际的 bug 或反例。比如 philosophy.md 里记录了 damage queue 存 derived value 导致的 bug，AI 读过后在类似场景下能更准确地避免同类错误。

  4. 保持对话粒度适中：一次性给太多任务，AI 容易遗漏。如果一个任务预计要改 10 个文件，拆成 2-3 步，每一步确认后再继续，总效率反而更高。

  5. 测试是 AI 最强的场景之一：让我手动写 1332 个测试我绝对不可能，但让 AI 生成测试框架 + 我来审核核心断言，这种方式把测试覆盖率从前 AI 时代的"能省就省"推到了"能写就写"。这可能是整个开发流程中受益最大的一环。

五、心态上的变化 ​

最开始用 AI 写代码时，我会习惯性地审查每一行——毕竟"AI 写的代码能信吗"。

过了一段时间，我发现自己花在审查上的精力其实和花在"手动写那些样板代码"上的精力差不多，但输出速度翻了好几倍。于是审查策略从"逐行审查"变成了：

  • 核心逻辑（战斗公式、并行安全、状态机）→ 自己写，AI 辅助
  • 周边代码（UI、配置加载、数据结构填充）→ AI 写，自己审查接口和边界条件
  • 模板代码（测试、文档、日志）→ AI 全权负责，抽查即可

这个分工让我的精力从"代码生产"转移到了"设计决策 + 质量控制"。独立开发者最大的瓶颈不是写不快，而是同时要做设计/开发/测试/文档，精力被切割得很碎。AI 帮我把开发和文档的时间压到了原来的 1/3~1/2，让我有更多时间做设计层面的决策。

当然，前提是你得先把自己想做什么想清楚——设计文档写到字段级别的详细程度，AI 才能精准执行。

参考文献 ​

  • 本项目 [AGENTS.md]（归义军传说项目约定）
  • 本项目 [CHANGELOG.md]（归义军传说变更日志）
  • BattleSystem-ECS [AGENTS.md]（ECS 项目约定）
  • BattleSystem-ECS [docs/philosophy.md]（ECS 项目工程理念）
  • GitHub — 归义军传说 SRPG（个人项目）
  • GitHub — BattleSystem-ECS（个人项目）