AI编程工程实践心得

探索模型

1. codex，kimiK3
2. deepseek + codex / deepseek + reasonix

特点

AI模型特点

1. 优先选择最短路径，而不是最优架构
2. 以解决问题为主，而不是长期维护为主
3. 同一个问题，不同的会话，结果存在不一致（模型概率问题）
4. 项目内容过大，容易出现上下文幻觉（生成不存在的内容）
5. 每一次新的对话，经验，上下文不会保留，需要重新提醒（恢复上下文，还原现场）
6. 越模糊的需求，实现路径越多样，越容易不满足约束
7. 顶尖模型成本过高，token计价过高，使用过快。
8. 大模型本质是一个文本输出模型，不同的Agent（脚手架）提供的能力存在差异（deepseek + codex 工程化能力约有deepseek + reasonix的20%左右的能力提升）

问题

短期会话问题

1. 如何让AI充分理解人的需求，输出思想一致的内容
   1. 反复对话，不断对齐思路，没有对齐思路时，不进入开发
   2. 借用精准语言表达，例如伪代码，mermaid语法流程图
2. 如何减少AI的上下文幻觉
   1. 让AI深入代码，寻找接口（不完全可靠，依赖模型能力），人工 code review 关键接口调用点。
   2. 编写测试用例，写出符合功能需求的测试代码（近似方案，作为上一条的交叉验证）
   3. 让AI自行完成编码-编译-运行的全流程，补充日志，输出具体运行日志信息，让AI完成编码-运行-调试的闭环。AI 有时会修改测试用例来强行通过而非修复 bug，需保持人工审查节点。
   4. 补充项目wiki上下文结构
3. 每一次新的对话，都需要重复恢复现场，还原场景，费时又费力，成本浪费
   1. 补充项目wiki上下文，让AI快速理解项目结构
   2. 保存对话精简上下文，让AI快速理解用户需求
   3. 补充项目代码结构索引，让AI快速理解项目代码调用流程
4. 每一轮复杂的需求对话，在AI解决问题，编码的过程中，可能会出现跑偏，例如修复某个编码问题不断死循环，修复某个边界问题而忽略主要问题（因为AI会寻找最短路径，可能会存在输出欺骗，也就是假代码给出真解决）
   1. 需要回归文档，AI输出解决手段，路径，任务，在约束的情况下，AI每一个编码与修复都是给文档打勾
   2. 设置「跑偏熔断」：同一问题修复超过 N 轮未收敛时强制停下来，回到设计文档重新对齐，而不是继续堆修补。
5. AI总是喜欢自造工具，而不是使用成熟的工具，导致浪费大量的上下文用于造工具
   1. 充分利用成熟的工具，例如mcp
   2. 充分进行公共类库的抽象和泛化使用。

长期项目维护问题

1. 大型项目，代码上下文，业务上下文结构过长，AI读一轮项目内容需要大量理解，不仅烧大量token，成本过高，还可能出现幻觉等相关问题
   1. 建立项目wiki + 代码结构索引
2. 简单项目，不断用AI对话，由于上下文截断，会话的重置，会导致，人脑的经验不一定能贯彻整个项目开发流程，会不断导致因为上下文的缺失，约束的不完整影响到开发质量，会导致AI开发的项目越来越难以维护
   1. 建立项目wiki，补充项目约束脚本，项目门禁等
   2. 利用已有的工具，例如git hook钩子，通过py脚本等方式，以强制的方式，不满足规范的代码不予提交，建立强约束
   3. 利用 AI agent 产品加载 AGENTS.md 的运行时机制（agent 运行时的上下文加载行为），在 AGENTS.md 里设置引导，让 AI 读取时同步加载其他约束文件，或人为引导 AI 理解对应规范信息。
   4. 定期让AI审查项目代码，关键约束进行审查，防止项目结构漂移。

约束体系分层（重要补充）

上述手段本质是两类

层级	手段	性质	失效风险
强制层	git hook 门禁、编译检查、测试用例、CI 静态分析	不可绕过，确定性	低（脚本 bug 除外）
引导层	wiki、AGENTS.md、提示词、SDD 文档	提高模型守规概率	高（模型可能不读、读漏、误解）

原则：能下沉到强制层的约束，绝不停留在引导层。 引导层负责"知道"，强制层负责"必须"。把 pre-commit 校验视为把约束治理从"评审期事后发现"前移到"提交前拦截"的关键手段 。

解决手段

思想：

1. 确定性优先：脚本优于模型输出，能够用脚本覆盖的内容，不要用模型进行输出。能用工具的地方，不要手动造轮子。
2. 先设计，后实现，参考SDD（Spec-Driven Development）流程

Vibe Coding 是先易后难。SDD 是先难后易。

SDD（Spec-Driven Development）是一种以明确规范为基础驱动开发流程的软件工程方法，核心理念是"规范先行"，即先通过结构化文档清晰定义系统"做什么"和"为什么"，再指导代码实现。其典型工作流包含编写规范、制定计划、拆解任务和AI辅助实现四步，强调规范作为单一事实来源，要求变更时优先更新规范而非代码。

3. 文档留痕，文档同步：设计文档留痕，确保编码不跑偏，文档同步，确保项目wiki最新，同步维护
4. 及时治理：过时的设计抛弃，最新的设计保留，删除旧规范，保留新规范。上下文文档建议增量更新而非整体重写

SKILL

1. spec-driven-dev，SDD流程Skill，非常重，8个流程，非常消耗token，但是可以充分把控质量和需求对齐，每一个环节可以人工确认，可以由高质量模型进行设计，低质量模型进行编码，高质量模型进行审查。文档留档，模型切换可以恢复现场。可自行裁剪
2. engineering-workflow，项目wiki搭建工具，在项目初始化的时候，充分进行项目架构设计，通过此skill建立好项目门禁，项目约束，项目骨架，项目原则，项目流程。然后在开发过程中，不断优化和补充，让每一轮对话都能够自行引导模型进行约束理解，结合SDD流程，可以进行模型切换，恢复现场的同时，保证项目约束，减少人为输入可能存在遗漏的规范等信息对齐。
3. mermaid-diagrams，流程图代码描述skill，减少AI的ASCII的一个流程输出，减少AI幻觉，精简质量，相当于伪代码
4. engineeringworkflow-nosdd 没有SDD流程的版本，减轻流程

可参考链接：https://github.com/corgic2/engineering-skill.git

效果/心得

通过上述设计，在具体的项目中，完成了项目骨架的治理，具体效果如下：

1. 每一次对话，简单说明一句："请理解项目"即可，由于引导设计Agents，不需要额外再说明项目规范，模型自己就会加载并理解
2. 每一次对话，不需要额外再说明其项目具体设计，都记录在项目wiki内。
3. 每一轮需求，模型会反复与人确认设计思路是否合理，由用户排版确认执行的时候，模型才会开始进行下一步
4. 可以采用codex，kimi完成多模态的理解与设计，采用deepseek进行编码。上下文不需要提醒，只需要让模型"理解项目，恢复XXX的sdd流程现场"，建议多模态的理解与设计采用codex或kimi全程，而逻辑的设计可以采用codex，kimi进行设计，deepseek完成编码，目前适用于留档的上下文对话，考虑成本的同时需要接受一定量的因上下文未对齐导致的质量损失问题。
5. 项目自行包含测试用例，每一次编码自行验证项目编译是否成功，修复编译问题，采用端到端的测试用例进行自行测试。
6. 项目门禁检查，每一次AI提交时通过脚本检查提交的代码是否满足约束，否则不予提交。例如不允许使用匿名空间，不允许使用XXX，以及SDD流程检测，例如：workflow-state的状态是否到最后一个阶段，如stage: "acceptance-retrospective"，如果是中间态，则不予提交。

展望

1. 如何高效方便解决多模态问题，不依赖顶尖大模型识图能力，例如 UI/设计稿转结构化描述（DSL、组件树 JSON）后交给低成本模型；用 OCR/布局解析等传统确定性工具前置处理图像，把"识图"降级为"读文本"。
2. 探索如何进一步减少AI对项目结构代码的完整性阅读，减少文档输入的同时提高输出的质量，例如代码结构索引升级为可检索的语义索引如codegraph，按需注入而非全量阅读；上下文文件加元数据做渐进式披露，如何设计代码wiki，并同时治理上下文漂移
3. 探索如何进一步提高Agent 记忆与经验沉淀，目前"恢复现场"靠 wiki + SDD 文档，较长的sdd流程将成为负资产，不再被项目需要，需要探索把每一轮需求设计从 wiki 中独立成分层记忆：工作层（日志/daily notes）→ 长期层（决策与约束），避免囤积大量sdd负资产。
4. 探索如何进一步提高质量把控，当前设计共同缺口是"AI给AI生成的质量打分"，AI生成的代码量过多，人工难以审查。可以尝试选择多评审者打分 + 校准的上游评估层思路 ，问题是如何设计跨agent质量打分，或者多模型打分，考虑量化等相关问题
5. 高/低成本模型切换目前依赖 SDD 文档留档，可进一步定义机器可读的交接格式（任务状态、已决约束、未完成项），把"恢复现场"从自然语言提示升级为结构化状态同步。
6. 门禁规则目前人工提出，人工编写，人工复盘，可探索从 code review 记录中自动挖掘"反复被 AI 违反的约定"，自动生成候选规则进入门禁，如何设计上述自动化审查流程