AI 编码中，哪些技术文档值得沉淀？

AI 辅助编程最容易制造一种错觉：只要模型足够强，它就应该能够从代码中自动还原出项目的一切。

但代码更擅长表达“系统现在怎样运行”，却很难完整解释“为什么必须这样做”。一个仓库里可能同时存在新旧两套架构，某个看似多余的兼容分支可能对应一批历史设备，而一个命名普通的 Repository 也可能承担着离线优先和数据冲突解决的职责。这些隐藏在团队经验、会议记忆和历史事故里的信息，才是 AI 生成可用代码时真正稀缺的上下文。

因此，技术文档的价值不只是方便新人入职，而是将项目的意图、边界和验证方法外化，让人和 AI 都能在可检查的事实上协作。

不是文档越多，AI 生成的代码就越好

把几十页通用编程规范全部塞进上下文，不但不会让 AI 更懂项目，反而会稀释真正重要的约束。一项知识是否值得沉淀，可以先问四个问题：

1. 它是项目特有的吗？ 通用的 Kotlin 语法没必要重写，但“车机熟睡后如何恢复空调状态”属于项目知识。
2. 它会影响技术决策吗？ 如果不知道这条信息，AI 会选错模块、依赖方向或数据源，就应该记录。
3. 错一次的代价高吗？ 涉及支付、隐私、账号、数据迁移和多进程通信的约束，应优先级更高。
4. 它会重复出现吗？ 反复解释过三次的事情，通常就值得从聊天记录进入仓库。

一个好的文档体系应该是分层的：

AI 当前的问题	最适合的信息载体
这是什么项目，如何跑起来？	README.md
我应该去哪里找，有什么不能做？	AGENTS.md
系统如何组成，依赖为何这样流动？	ARCHITECTURE.md
这个功能应该表现成什么样？	Product Spec / 接口与数据契约
当时为什么选 A 而不是 B？	ADR / Design Doc
遇到这类任务时应该怎样做？	Rules / Skills
一项长任务已经做到哪里？	Execution Plan / 技术债记录
怎样证明修改是对的？	Tests / Checks / Hooks

README：先给出一条可复现的路

README.md 是人和 AI 进入项目的第一个入口。它最重要的任务不是展示项目历史，而是用最短路径回答：

• 项目解决什么问题，主要功能是什么；
• 依赖哪些工具和版本；
• 如何完成最小构建、运行和测试闭环；
• 哪些配置需要本地提供，但不能提交到仓库；
• 去哪里继续阅读架构、业务和发布文档。

以 Android 项目为例，只写“使用 Android Studio 打开项目”是不够的。更有用的 README 会明确 JDK 与 Android SDK 要求、demo/staging/production 等 Build Variant 的用途、本地配置模板以及可复制的命令：

./gradlew :app:assembleDemoDebug
./gradlew :feature:login:testDemoDebugUnitTest
./gradlew connectedDemoDebugAndroidTest

这样 AI 才不会在修改完 feature-login 后，错误地执行一个仓库从未支持过的通用命令。README 中应该放置配置文件的创建方法，但不应记录真实密钥、签名密码或生产环境凭证。

Google 的官方示例项目 Now in Android 展示了一种很实用的 README 写法：它明确 demo 变体使用本地数据、prod 变体依赖真实后端，日常开发使用 demoDebug，性能测试使用 demoRelease。这些信息不是泛泛的项目介绍，而是直接影响 Agent 如何构建、测试和解读运行结果的操作契约。

AGENTS.md ：做导航地图，不做百科全书

AGENTS.md 回答的是：Agent 进入这个仓库或目录后，应该如何开始工作？

它可以包含：

• 项目与模块地图；
• 最常用的 build、test、lint 命令；
• 全局性的高优先级约束；
• 禁止手改的生成目录和高风险区域；
• 指向 ARCHITECTURE.md、产品规格、专项 Skill 和更深层文档的链接。

但它不应该详细罗列“支付模块的 38 个异常场景”。这些内容应归入支付产品规格或设计文档，AGENTS.md 只负责告诉 Agent 什么时候去读它。

OpenAI 公开的 Harness Engineering 实践 也强调过这个问题：一份巨大的 AGENTS.md 会挤占上下文、模糊优先级，而且很容易过时。他们最后采用的是“短 AGENTS.md + 结构化 docs/ 知识库 + 按需读取”，并将仓库内的知识作为事实源。

一个 Android 项目的 AGENTS.md 可以只给出这样的索引：

# Project map

- `:app` 只负责应用装配和根导航。
- 业务 UI 位于 `feature/**`，数据实现位于 `data/**`。
- 模块边界与依赖方向见 `ARCHITECTURE.md`。
- 修改 Room Entity 前必须读取 `skills/room-migration/SKILL.md`。
- 不要修改 `**/build/` 和自动生成的 API 模型。
- 最小验证：`./gradlew testDebugUnitTest lintDebug`。

当仓库很大时，还可以在子目录中放置更局部的 Agent 指南。根目录仅保留全局规则，feature-player/ 下的文档再解释播放状态机、音频焦点和后台播放的特有约束。

ARCHITECTURE.md ：记录边界和数据流，而不只是目录树

ARCHITECTURE.md 是系统地图。它要让 AI 理解的不是“仓库中有哪些文件夹”，而是：

• 模块的职责边界和对外 API；
• 允许与禁止的依赖方向；
• 状态的所有者和单一事实源；
• 关键数据流、进程边界与线程策略；
• 系统的已知限制和质量验证方法。

Google 的 Android 架构建议 推荐清晰的 UI 层和数据层、由 Repository 暴露数据、单向数据流等原则；多模块指南 也强调高内聚、低耦合以及隐藏模块内部实现。但这些是通用建议，项目文档还需要把它们翻译成当前仓库的具体事实。

假设一个内容类 Android 应用支持离线阅读，只在架构文档里写“项目采用 MVVM + Repository”，对 AI 的帮助非常有限。更有效的写法是明确：

Compose Screen
    ↓ UiState / UiAction
ViewModel
    ↓
ArticleRepository
    ├─ Room：UI 可观察的唯一数据源
    ├─ Network：只负责拉取远端数据
    └─ WorkManager：负责可重试的后台同步

并继续记录：UI 不直接消费网络响应；用户离线收藏时先写入 Room 的待同步状态；恢复网络后由 WorkManager 上传；冲突时以服务端版本和本地操作时间共同判定。

知道这些之后，AI 才不会为了“尽快显示新数据”而绕过 Room，把 Retrofit 返回值直接塞给 ViewModel，破坏离线一致性。

Now in Android 的架构文档 是一个更具体的参考：它先记录架构目标，再解释分层与数据流，然后以 For You 页面为例，按执行顺序列出 WorkManager、Repository、Room、Network 和 ViewModel 之间的交互，并在每一步旁边给出可搜索的代码符号。这比只画一张分层图更适合 AI，因为它同时提供了“设计意图”与“源码入口”。

Product Spec 与接口契约：说清楚“正确”是什么

架构文档说明系统如何组成，产品规格则定义功能的可观察行为。很多 AI 生成代码“能运行但不符合预期”，并不是因为模型不会写代码，而是项目从未对边界情况给出一致答案。

以 Android 登录为例，“实现过期后自动刷新 Token”至少还存在这些问题：

• 多个请求同时收到 401 时，只允许一次刷新，还是每个请求各自刷新？
• 刷新失败后是退回登录页、保留本地数据，还是继续离线模式？
• 用户通过 Deep Link 打开受保护页面时，登录后是否要恢复原始导航目标？
• 进程被系统回收后，哪一部分会话状态可以从持久化存储中恢复？

如果这些行为没有进入产品规格和验收条件，AI 只能自行猜测，而且每次猜测可能都不一样。

一份能直接用于编码的 Product Spec，不必很长，但要把触发条件、状态转换和验收结果写成可判定的句子。例如：

# 受保护 Deep Link 的登录恢复

- Status: Accepted
- Owner: Account Team
- Entry: `myapp://order/{orderId}`

## 行为契约

| 条件 | 预期行为 |
| --- | --- |
| 已登录，订单存在 | 直接进入订单详情 |
| 未登录 | 进入登录页，保留经校验的目标路由 |
| 登录成功 | 只恢复一次原目标，不重复入栈 |
| 用户取消登录 | 返回首页，清除待恢复目标 |
| 登录期间进程重建 | 从 `SavedStateHandle` 恢复非敏感路由参数 |

## 安全与边界

- 不在 Intent、Bundle 或日志中保存 Token。
- `orderId` 必须通过格式校验，服务端仍需校验访问权限。
- 验收覆盖冷启动、后台恢复和系统回收进程三条路径。

这份规格不规定必须用哪个 Navigation API，而是定义了用户能看到的行为和不得突破的安全边界。实现时可再对照 Android 官方的 Deep Link 指南 与 UI 状态保存指南。

同样值得沉淀的还有机器可读的契约：

• OpenAPI / JSON Schema 定义的网络接口；
• Room 导出的 schema 与 Migration 测试；
• Protobuf 或 AIDL 定义的跨进程模型；
• Deep Link 路由、Intent extra 与返回结果约定；
• 设计 token、Compose 组件状态和无障碍要求。

例如新增一个 Binder IPC 时，仅有 .aidl 文件还不足以表达完整契约。文档还应明确调用方权限、Binder 线程上允许的工作量、服务断开后的重连策略、版本兼容方式以及数据大小边界。否则 AI 可能产生语法正确、却会阻塞 Binder 线程或破坏旧客户端兼容性的实现。

ADR 与 Design Doc：留住被代码隐去的理由

代码只能证明当前选择了什么，无法证明当时放弃了什么。ADR（Architecture Decision Record）适合保留重要技术决策，至少包含：

1. 决策背景与限制；
2. 考虑过的备选方案；
3. 最终决定与核心理由；
4. 已知代价与后续影响；
5. 什么条件发生变化时需要重新评估。

例如，一个 Android 应用决定用 Room 作为文章列表的单一事实源，并不代表这是所有项目的“标准答案”。ADR 应记录真正原因：应用必须在地铁、飞行模式和弱网环境下保持可读；代价是需要数据库迁移、同步状态和冲突解决机制。下次 AI 处理列表刷新问题时，才不会用“减少一层存储”为理由轻易删掉 Room。

对应的 ADR 可以写成下面这样：

# ADR-007：文章列表以 Room 为唯一读取源

- Status: Accepted
- Date: 2026-08-21

## Context

首屏必须在无网和弱网下可读，收藏操作需要离线生效。

## Decision

上层只观察 Room；网络返回值先写入 Room，再由 `Flow` 通知 UI。
后台同步使用唯一 WorkManager 任务并采用指数退避。

## Alternatives

- 网络数据直接进入 UI：实现简单，但会产生本地与内存两份状态。
- 仅使用内存缓存：无法满足进程重启与离线阅读。

## Consequences

- 必须维护 schema、Migration 和同步冲突策略。
- 功能测试必须覆盖无网启动、重试和进程恢复。

## Revisit when

产品明确取消离线能力，或数据规模已不适合端侧持久化。

Android 官方的 Offline-first 架构指南 同样把本地数据源作为上层读取的事实源，并建议用持久队列与 WorkManager 处理需要重试的同步。引用这类上游资料可以说明原理，但 ADR 仍需要保留本项目的特有条件和取舍。

Design Doc 更适合跨模块、高风险或方案尚在演进的功能，如多进程播放架构、车载多屏协同、支付链路改造。它可以比 ADR 更详细，但一旦决策落地，仍要标明状态，避免 AI 把“讨论中的选项”当成“已生效的规则”。

GLOSSARY：把团队默认知道的话说清楚

AI 非常容易在同名异义和同义异名上犯错。GLOSSARY.md 的作用是统一项目语义，特别是那些无法从类名中准确推断的业务概念。

车载 Android 应用就很典型：“账号”“驾驶员档案”和 Android UserHandle 可能是三个不同概念；“熄火”也不一定意味着应用进程立即终止，还可能经历限功率、挂起和唤醒。如果这些词没有明确定义，AI 很可能把业务账号 ID 当成系统用户 ID，或在电源状态变化时错误清空本应恢复的状态。

词汇表不需要很长，但应包含“定义、非定义、代码对应物和相关链接”。其中的命名还应该与 Product Spec、API Schema 和代码保持一致。

某个车载项目可以将词汇表写成：

术语	本项目中的定义	不代表	代码对应物
业务账号	登录云端服务的身份	Android 系统用户	AccountId
驾驶员档案	座椅、空调、媒体偏好等可同步设置的集合	登录凭证	DriverProfile
Android 用户	由系统多用户机制隔离应用数据的用户空间	必然已登录某个业务账号	UserHandle
唤醒恢复	车机从 Suspend-to-RAM 返回可交互状态	冷启动或新进程创建	PowerState.SUSPEND_EXIT

AOSP 的 Android Automotive 用户与账号文档 明确指出，账号包含在某个 Android 用户中，但两者并不互相定义；车载电源管理文档 则区分了 suspend、hibernate、shutdown 以及对应的进入和退出状态。这正是 Glossary 应优先收录的内容：名称相似、但选错会导致数据隔离或生命周期错误的概念。

Rules：放稳定、局部、可判定的硬约束

Rules 适合表达“只要修改这类代码，就必须遵守什么”。好规则应该短小、稳定、尽可能可以被检查。例如：

• feature/** 可以依赖 core/**，core/** 不得反向依赖业务模块；
• Compose UI 和 ViewModel 不得直接访问 Retrofit Service 或 Room DAO；
• ViewModel 不持有 Activity、View 或其他生命周期对象；
• 修改公开 Kotlin API 时必须更新 API dump 并执行兼容性检查；
• 修改 Room schema 时必须提供 Migration 与迁移测试。

在 Cursor 中，项目规则可以放在 .cursor/rules/ 下的 .mdc 文件中，通过 frontmatter 描述适用范围和加载方式，具体行为应以当前的 Cursor Rules 文档 为准。例如：

---
description: Android data layer rules
globs: "{data,feature}/**/*.kt"
alwaysApply: false
---

# Android Data Layer

- UI 层不直接引用 DAO 或 Retrofit Service。
- Repository 负责协调本地与远程数据源。
- 跨层暴露的持续状态使用 `Flow`。
- 错误类型在数据层边界转换，不向 UI 暴露 HTTP 实现细节。

规则不应记录所有代码偏好。如果一条内容经常例外、需要长篇背景才能解释，它更可能属于架构文档或 ADR，而不是一条应被无条件注入的 Rule。

Skills：将专项经验变成可重复执行的 SOP

Rule 解决“必须遵守什么”，Skill 解决“这类任务具体怎样做”。Skill 适合按需加载的步骤、脚本、检查项和专业知识，例如：

• 如何排查账号登录失败；
• 如何为 Room 数据库新增字段；
• 如何新增一个 Binder IPC 并验证版本兼容性；
• 如何创建新的 Android Feature Module；
• 如何排查 Compose 重组过多和列表卡顿；
• 如何完成 targetSdk、AGP、Kotlin 或 Compose 版本升级。

以“新增 Room 字段”为例，一份有效的 Skill 不只是告诉 AI 修改 @Entity，而是要引导它：

1. 确认当前数据库版本和导出 schema；
2. 分析旧用户数据如何生成新字段，避免用无意义默认值掩盖问题；
3. 编写 Migration，不使用破坏数据的 fallback；
4. 增加从历史 schema 升级到当前版本的测试；
5. 执行指定 Gradle 任务，并核对新的 schema diff；
6. 更新与该字段有关的 API 契约或业务规格。

这样的 Skill 保存的不是模型本来就会的 SQL 语法，而是团队对数据安全的实际工作流。

Execution Plan：让长任务可以中断、恢复和复查

小修改可以在一次对话中完成，但跨模块改造、数据迁移和大版本升级往往会经历多次上下文切换。此时应把计划作为一等文档，记录：

• 目标、非目标和验收标准；
• 分阶段任务与当前进度；
• 已验证的事实、失败尝试和决策日志；
• 风险、回滚策略和剩余问题；
• 每个阶段的验证命令与结果。

比如将一个大型 Android 应用升级到新版 AGP，通常会同时触发 JDK、Gradle、Kotlin、KSP 和三方插件的兼容问题。如果 AI 每次都从头探索，它可能重复已失败的组合，甚至撤销前一阶段为了兼容性做出的决策。一份持续更新的执行计划，就是这项任务的外部记忆。

这类计划最好不只写待办清单，而是把每个阶段的输入、验证和退出条件写清楚：

# AGP 升级执行计划

## Goal

完成 AGP 与 Gradle 升级，不改变业务行为和发布签名流程。

## Progress

- [x] 记录升级前基线：构建时间、APK 大小、lint 结果、关键测试
- [x] 升级 Gradle Wrapper 和 AGP，保持 Kotlin/KSP 暂不变
- [ ] 处理 convention plugin 与第三方插件兼容问题
- [ ] 验证 `demoDebug`、`prodRelease` 和 `benchmark` 变体
- [ ] 执行单测、仪器测试、lint 与关键用户路径冒烟测试

## Decision log

- 08-21：不同时升级 Compose，避免扩大回归范围。
- 08-21：插件 X 在配置阶段使用已移除 API；先升级插件，不使用本地 patch。

## Rollback

保留升级前 Wrapper 与 Version Catalog 版本；数据库和网络契约未变，可整体回退构建工具链。

计划中的“不同时升级 Compose”和“已失败的插件处理方式”，对后续 Agent 的价值往往比打勾本身更高。它们防止后续会话悄悄改变任务边界或重走已证明不通的路。

Tests 与 Hooks：把“应该正确”变成“可以证明”

仅有文字约束，AI 仍然可能理解错误或遗忘执行。测试、静态检查和自动化脚本可以视为“可执行的文档”，它们用确定性反馈补足了自然语言的模糊性。

在 Android 项目中，可以将不同类型的约束落到对应工具上：

• 用 Gradle 模块依赖检查阻止 core 反向依赖 feature；
• 用 lint、Detekt 和 API 检查器固化编码与兼容性规则；
• 用 Room Migration Test 保护用户的历史数据；
• 用 Compose UI Test 和截图测试保护关键交互与视觉状态；
• 用 Macrobenchmark 定义启动、首页滑动、搜索等关键用户路径，并持续验证 Baseline Profile；
• 用 CI 统一执行必要检查，而不依赖人或 AI 记住所有命令。

测试文档最值得写的，并不是“项目有单元测试”，而是修改类型与验证集合之间的映射。例如可以在 QUALITY.md 中写：

改动类型	最小必须验证	需要人工确认的输出
Room Entity / DAO	Migration Test + Repository Test	导出的 schema diff
Compose 布局	UI Test + 截图比对	手机、平板、深色模式差异图
启动链路	Macrobenchmark + Baseline Profile 生成	启动时延基线和 profile diff
Deep Link / 登录	导航测试 + 进程恢复测试	未登录、取消登录和越权路径
权限申请	UI Test + 拒绝/撤销冒烟测试	拒绝后是否可降级使用

Now in Android 的 README 就记录了这类信息：它明确支持的测试变体，说明为什么不应直接运行覆盖全部变体的通用任务，并分别给出截图基线的记录、验证和差异比较命令。这能避免 AI 遇到截图失败时，不经审查就重新生成基线，把真实回归一起覆盖掉。同样，Android 官方的 Core app quality 清单 可以作为测试计划的上游参考，再结合项目自身的关键路径做裁剪。

Hooks 可以在 Agent 读取、编辑、执行命令或停止前后触发脚本。它适合自动格式化、检查敏感信息、阻止高风险命令，或在任务结束前提醒更新文档。如果使用 Cursor，可参考官方的 Hooks 文档。

但 Hooks 不应该隐藏关键规则。人和 AI 都应该先能从文档中理解“为什么要检查”，再由 Hook 负责“确保它真的被检查”。

Subagent：是知识的消费者，不是知识本身

Subagent 很适合在大型工程中进行专项审查，如 architecture-reviewer、test-reviewer 和 security-reviewer。独立上下文能够隔离大量探索过程，但专业 Agent 的名字并不会自动带来专业性。

架构审查 Agent 需要读到当前的模块边界和 ADR，测试审查 Agent 需要知道关键用户路径和历史回归风险，安全审查 Agent 则需要了解数据分类、权限边界和威胁模型。因此，Subagent 是对知识库进行按需分工的方式，不能替代知识库本身。

如果要为 Android 位置权限创建 privacy-reviewer，它的文档至少应定义五件事：

# privacy-reviewer

- Trigger: Manifest 或权限请求代码变更时
- Read first: `docs/privacy/data-classification.md`、相关 Product Spec
- Check: 最小权限、按需请求、Rationale、拒绝后降级、日志泄漏
- Evidence: Manifest diff、调用点、对应测试和官方规则链接
- Output: 只输出按严重程度排序的发现；无证据时不判定通过

这个例子里，“安全审查”被缩小成一个可验证的 Android 任务，检查项也可与 Android 隐私与权限建议 对齐。比起只写“你是一名资深安全工程师”，这些输入、边界、证据和输出格式更能稳定审查质量。

一个 Android 功能，如何沉淀成一组可用的文档

以“离线收藏文章”为例，不同文档不是在重复同一段描述，而是各自回答不同问题：

文档	应记录的内容	对 AI 的作用
Product Spec	离线时点击立即生效；恢复网络后同步；冲突规则与错误提示	定义用户可观察的正确行为
Architecture	Room 是事实源，Repository 协调数据源，WorkManager 负责后台同步	阻止 AI 绕过分层制造第二份状态
ADR	为什么选择本地优先，接受了哪些复杂度	避免后续“简化”时破坏核心能力
Rules	UI 不直接调 DAO；同步任务必须幂等；持续任务不依赖界面生命周期	在生成代码前约束局部决策
Skill	新增字段、Migration、Worker、测试和验证命令的顺序	让同类修改遵循一致 SOP
Tests / Checks	迁移测试、冲突测试、进程恢复测试与 Worker 重试测试	对生成结果给出确定性反馈

当这套信息存在时，我们不需要在每次对话里重新讲述离线业务的完整历史。Agent 先从 AGENTS.md 找到地图，再根据任务只读相关规格、ADR 和 Skill，修改后由测试闭环。这才是技术文档对 AI 编码的实际价值。

如何避免文档漂移

过时文档比没有文档更危险，因为它会以“事实”的外观给 AI 错误指引。沉淀文档时，需要同时设计它的维护机制。

一个事实只保留一份权威来源

接口字段应以 OpenAPI 或 Schema 为准，README 只链接它；数据库结构应从 Room schema 生成，不要另外手写一份容易失真的字段表。能从代码或构建产物生成的文档，尽量自动生成。

写决策与边界，少复制教程

“如何使用 StateFlow”可以链接官方文档；“本项目的 UiState 为什么不暴露一次性事件”才是应该进入仓库的决策。越接近项目独有语义的内容，沉淀价值越高。

让文档能被验证

文档中尽量给出代码入口、验证命令、负责人或最后校验状态。架构图描述了模块依赖，就尽可能用脚本比对真实 Gradle 依赖图；规则说“不能直接调 DAO”，就尽可能用模块可见性或静态检查使其无法轻易违反。

Now in Android 的模块化文档 给出了一个很好的防漂移案例：每个模块的 README 都包含依赖图，依赖变化后由工作流自动更新，也可以通过 graphUpdate 任务手动重新生成。因此 Agent 看到的不是人工维护的“理想依赖图”，而是可以从构建配置重建的当前事实。

把更新文档纳入完成定义

可以在 Agent 规则或任务结束检查中写入：

完成修改前：

1. 评估代码是否改变了架构、对外契约、业务语义或操作流程。
2. 如有变化，更新对应的事实源并运行文档检查。
3. 如无需更新，在总结中说明原因。

关键不是让 AI 每次都修改文档，而是让“代码已变、文档是否仍然成立”变成必须回答的问题。

一份可以起步的目录结构

对于一个中大型 Android 项目，可以从下面的最小结构开始，再根据项目复杂度增删：

README.md
AGENTS.md
ARCHITECTURE.md
docs/
├── glossary.md
├── product-specs/
│   ├── index.md
│   └── offline-bookmarks.md
├── decisions/
│   └── 0001-room-as-source-of-truth.md
├── design-docs/
├── exec-plans/
│   ├── active/
│   ├── completed/
│   └── tech-debt.md
├── contracts/
└── generated/
skills/
├── room-migration/
└── compose-performance/
.cursor/
├── rules/
└── hooks.json

不需要在项目第一天就创建所有目录。最实用的做法是：先写好 README 和简短的 AGENTS.md，再将开发中反复出现、一旦理解错误就会产生较大代价的知识，逐步归入对应层级。

总结：为 AI 沉淀的不是更多文字，而是更少猜测

一份好的技术文档，应该能够直接减少一类错误决策：README 减少环境猜测，AGENTS.md 减少导航猜测，Architecture 减少边界猜测，Spec 与契约减少行为猜测，ADR 减少设计动机猜测，Rules 与 Skills 减少操作猜测，而 Tests 与 Hooks 减少结果猜测。

真正成熟的 AI 编码工程，不是在每次对话中写出更长的 Prompt，而是将那些曾经只存在于资深工程师脑中的判断，变成仓库内可导航、可按需读取、可验证、也可以随代码一起演进的工程资产。