用户旅途：你一定踩过的坑
下面每一个旅途，都是 AI 写代码时真实发生的事情。 如果你用 AI 编程超过一周，你至少经历过其中三个。
旅途 1：永远在膨胀的文件
你："给 Dashboard 加个用户设置。"
AI 加了 80 行。文件现在 280 行。没问题。
你："再加通知偏好设置。"
AI 又加了 120 行。400 行。还行。
你："加个数据导出功能。"
又加了 150 行。550 行。然后是活动日志。然后是 API Key 管理。文件现在 900 行了。 没有任何人类开发者会让一个文件膨胀到这个程度——他们在 ~300 行时就会本能地拆分。但 AI 没有这个本能。它没有"太大了"的记忆。它只优化"完成当前请求"，而不是"维护代码库的健康"。
Archon 怎么做
Reviewer 守护进程 在结构审计（维度 2）中主动检测文件膨胀。当文件越过阈值时：
- 标记膨胀 — "这个文件有 5 个职责，按关注点分离拆分"
- 提出具体拆分方案 —
UserSettings.tsx、NotificationPrefs.tsx、DataExport.tsx - 向前约束 — 代码质量驱动 中写着
❌ 文件超过 300 行——按职责边界拆分
文件不会悄悄膨胀。系统会捕捉并行动。
旅途 2：同一个概念，五种写法
第 1 周：AI 用 useState + useEffect 写数据获取。 第 2 周：AI 用 useSWR——它"学到了"更好的模式。 第 3 周：AI 选了 RTK Query——项目已经有 Redux。 第 4 周：回到原始 fetch，包在工具函数里。 第 5 周：自定义 hook 包裹 axios。
五种都能工作。每种单独看都没问题。但到了 60,000 行代码时，你有五套数据获取范式，每个新开发者（人类或 AI）都得猜哪个才是"对的"。
Archon 怎么做
Archon 的 约束系统 在模式确立后将其锁定。第一次数据获取方案被选定并验证后，它成为约束：
❌ 使用原始 fetch/axios 调用 API——使用已确立的 useSWR hook 模式每次后续会话中，这条约束在生成时注入到 AI 的上下文窗口——不是"以后读的建议"，而是在实时塑造代码输出的活跃规则。AI 不会漂移到另一种模式，因为禁令就是它指令集的一部分。
漂移检测 还跨会话监控模式不一致性，在代码库偏离已声明的模式时触发审查。
旅途 3：跨会话失忆
周一下午：你和 AI 花了 2 小时重构认证模块。你提取了共享的 useAuth hook，整合了 token 刷新逻辑，删除了三处冗余的认证检查。
周二上午：新的聊天会话。你说"给设置页面加基于角色的访问控制"。AI 写了一个全新的内联认证检查——正是你昨天花时间消除的模式。它对昨天的重构毫无记忆。
Archon 怎么做
Manifest 持久化地捕获项目级决策。周一重构结束后，manifest 记录了：
- 认证集中在
useAuthhook - Token 刷新在
authProvider中处理 - 不允许内联认证检查
周二的会话将 manifest 加载到上下文中。AI 看到已确立的模式并遵循它——不是因为它记得昨天，而是因为约束系统替它承载了记忆。
漂移检测 对比 manifest 的"认知地图"和实际代码状态。如果 AI 的理解落后于现实，系统会在下一个任务开始前强制同步。
旅途 4：复制粘贴驱动的开发
你："给用户页面加个数据表格。"
AI 写了 120 行：表格组件、排序、分页、搜索筛选。
你："在订单页面也加一个类似的表格。"
AI 复制了用户表格，改了列名。又是 120 行，90% 重复。
你："产品页面也要一个。"
三份副本。它们几乎完全相同——但排序逻辑、分页重置方式、搜索防抖时间各有微妙差异。当你修复一个表格的 bug 时，另外两个仍然有这个 bug。
Archon 怎么做
Soul 中编纂了三次法则："两次重复不是抽象的理由——过早泛化比重复更危险。"但到第三次时，系统触发：
- 模式识别 — Reviewer 识别到重复的表格模式
- 抽象提案 — 提取共享的
DataTable组件，配置化列定义、排序和分页 - 约束创建 —
❌ 复制表格/列表 UI 模式——使用共享的 DataTable 组件
此后 AI 使用共享组件而不是复制。Bug 修复自动传播。
旅途 5：错误处理各自为政
页面 A：API 出错 → 弹个 toast 通知。 页面 B：API 出错 → 顶部渲染红色 banner。 页面 C：API 出错 → 整个页面白屏崩溃。
每个页面在不同的会话中构建。每次 AI 都用当时看起来局部合理的方式"处理了错误"。用户体验是碎片化的：有时错误优雅降级，有时应用直接死亡。
Archon 怎么做
这就是 反馈循环 的运作。第一次页面因 API 失败而崩溃时，Stage 3.6（知识进化）捕获这个教训：
❌ 单个 API 失败导致整个页面崩溃——每个区块独立用 isError/refetch 包裹
❌ 不一致的错误展示模式——使用项目的 ErrorBoundary 组件这些成为永久约束。之后在 Archon 下构建的每个页面自动获得：
- 每个 API 区块独立的错误边界
- 通过已确立的模式统一的错误 UI
- 加载状态的骨架屏
第二个功能不会重复第一个功能的错误。第十个功能几乎刀枪不入。
旅途 6：配置散落各处
你的项目有：
- API 基础 URL 硬编码在 12 个文件里
- 环境变量定义在
.env、.env.local和两个配置文件里 - 主题色分别存在 CSS 文件、Tailwind 配置和三个内联样式对象里
- Feature flag 用三种不同机制检查
AI 不做整合。它看附近的代码，就近复制看到的模式，然后继续前进。项目慢慢变成一座配置迷宫，没有单一事实来源。
Archon 怎么做
Reviewer 的结构审计（维度 2）专门检测配置散乱：
- 散乱配置检测 — 发现同一个魔法字符串/URL/颜色值出现在多个文件中
- 集中化提案 — 提取到带类型导出的单一配置模块
- 导入边界执行 — Handoff 驱动 确保配置值从唯一的规范位置导入
约束系统防止回退：
❌ 硬编码 API URL、主题色或 feature flag——从 config/ 导入旅途 7："我电脑上没问题"的盲区
AI 构建了一个漂亮的仪表盘。每个组件在挂载时加载数据。五个 API 调用同时发出。在你快速网络的开发机上，800ms 加载完毕。看起来很棒。
到了生产环境，真实用户用移动网络：页面需要 8 秒加载，数据到达时布局跳动，慢连接的用户会看到 3 秒的空白屏幕。
AI 从不考虑 happy path 之外的用户。它不考虑慢网络、大数据集、屏幕外内容或基于视口的加载。
Archon 怎么做
异步加载驱动 包含 AI 不能跳过的架构约束：
❌ 不管滚动位置一次性触发所有 API 调用——使用 skip: !inView
❌ 异步区块没有骨架屏/加载状态——在数据前添加 Skeleton
❌ 没有错误恢复 UI——为失败请求添加重试机制这不是建议。这是 AI 在代码生成时的活跃指令集的一部分。AI 默认就会写出视口感知的、渐进加载的、错误恢复的代码——不是因为它聪明到想得到，而是因为约束系统不让它跳过。
旅途 8：代码写完了，说明书呢？
你让 AI 构建一套权限系统。它交付了：角色定义、中间件守卫、路由保护、一个 usePermission hook。能跑。你合并了。
两周后，新同事问："权限系统怎么工作的？有哪些角色？怎么加新角色？"你找文档。没有文档。 AI 写了 600 行代码，零行说明。
你回去让 AI："把权限系统文档写一下。"它写了个 README。但这时代码已经变了——README 一出生就是过时的。你让 AI 更新。它重新覆盖了一版，漏掉了前一版覆盖的边界情况。
每个功能都在重复这个循环。代码库在增长，但文档要么缺失、要么过时、要么自相矛盾。你造了一个产品，但除了逐行读源码，没人能理解它。
Archon 怎么做
Archon 把文档当作交付物，而不是事后补充。Demand 流水线在多个阶段强制执行这一点：
Manifest 更新（Stage 5） — 每个完成的功能都记录到项目 manifest 中：做了什么、在哪里、用了什么模式。这是项目的活目录。
知识进化（Stage 3.6） — 当 agent 发现新模式或做出架构决策时，它们被捕获到
proposed-rules.md和架构文档中——而不是作为部落知识留在某个人的聊天记录里。漂移检测 — 漂移机制 追踪文档是否反映现实。当代码变更速度超过文档更新，漂移计数器递增。到达阈值时，系统强制对齐："manifest 说认证用的 JWT，但代码已经换成了 session token——更新 manifest。"
重构报告 — 每次重大变更都产出结构化记录：改了什么、为什么、考虑过并拒绝了什么方案。这是项目的制度记忆——每个"做了什么"背后的"为什么"。
最终结果：你的项目始终拥有一份当前的、准确的自我地图。新成员（人类或 AI）读一下 manifest 就能理解系统，不需要考古。
规律
每个旅途的根源都一样：
AI 优化的是当前请求，而不是代码库的长期健康。
这不是缺陷——这是无状态、无记忆系统的本性。解决方案不是让 AI"想得更深"。解决方案是给它一个让正确选择成为默认选择的环境。
这就是 Archon Protocol：一个让 AI 的局部最优决策变成全局一致工程产出的操作系统。
| 没有 Archon | 有 Archon |
|---|---|
| 文件膨胀到有人注意为止 | 主动检测膨胀并拆分 |
| 模式跨会话漂移 | 约束锁定已验证的模式 |
| 昨天的决策被遗忘 | Manifest 持续承载决策 |
| 复制粘贴直到 bug 扩散 | 三次法则触发抽象 |
| 错误处理是逐页抽奖 | 反馈循环强制一致性 |
| 配置散落在项目各处 | 结构审计集中配置 |
| 只考虑 happy path | 驱动强制真实世界韧性 |
| 代码写完没有文档 | Manifest + 漂移检测保持文档同步 |