freedakgmail
8.0 KiB
8.0 KiB
AI Coding 通用方法与技巧
一套可迁移到任意项目的 AI 辅助编码（AI Coding）方法论：如何与 AI 高效协作、如何约束 AI 产出质量、如何让系统保持可回归与可审计。
一、核心方法论
1. 规格驱动开发（Spec-Driven Development）
先规格、后代码。把"需求 → 设计 → 任务"作为地面真值，再让 AI 据此实现：
| 阶段 | 产出 | 要点 |
|---|---|---|
| 需求 | 可测试、可追溯的需求描述 | 用结构化句式（如 WHEN/IF/WHERE/SHALL），每条需求都能映射到验收标准 |
| 设计 | 架构、数据模型、模块边界、正确性属性 | 明确不变量（invariants），它们将成为测试依据 |
| 任务 | 可执行的任务清单 | 拆到可独立实现并验证的粒度 |
收益：AI 有明确的"做什么"与"对错标准"，避免凭感觉发挥；改动前先回到规格确认，减少返工与漂移。
2. 确定性核心 + AI 语言层 的分层（最关键的架构原则）
凡涉及金额、评分、判定、裁决等关乎正确性与合规的逻辑，一律用确定性纯函数实现，绝不交给大模型；大模型只承担语言理解（解析、抽取、归类、摘要、预填）。
- 确定性核心：无副作用、可复算、相同输入恒得相同输出，便于测试与审计。
- AI 边界层：负责把自然语言/非结构化输入转成结构化数据；调用失败或超时时自动降级到确定性兜底，不阻塞主流程。
- 收益：把大模型的不确定性隔离在"翻译层"，不污染决策；系统结果稳定、可解释、可回归——这是合规与高可靠系统的硬要求。
3. 属性化测试（Property-Based Testing）
对核心逻辑写"属性"，而不仅是样例用例。属性描述对任意合法输入都应成立的不变量，例如：
- 输出值恒落在合法值域内；
- 派生结果与其定义函数恒等（如等级恒等于按分值分级的结果）；
- 幂等性：重复执行结果不变；
- 往返一致：序列化后再反序列化与原值等价；
- 局部不变：修改 A 不应影响与之无关的 B。
收益：用随机输入覆盖人想不到的边界；属性即"活的规格"，是重构时的安全网。
二、与 AI 协作的有效技巧
1. 小步快跑 + 每批验证
长任务拆成小批，每批改完立刻跑验证三件套（类型检查 / 静态检查 / 测试），全绿才进入下一批。绝不在未验证的情况下连续堆叠改动——否则错误会层叠，难以定位。
2. 用强类型/静态检查做护栏
开启语言可用的最严格静态检查选项。编译器/类型系统把大量运行期 bug 前移到编码期；AI 生成的代码尤其受益于强约束护栏。
3. 每个可工作的改动独立提交
一个改动完成并验证后立即提交，提交信息写清"根因 + 改法 + 验证方式"。便于回滚，也便于审计 AI 的每一步决策。
4. 根因优先，拒绝表面打补丁
遇到问题先定位根因再动手：
- 区分"数据/输入缺失"与"逻辑 bug"——前者加校验与提示，后者改逻辑。
- 区分"展示问题"与"计算问题"——不要用改公式来掩盖录入或展示缺陷。
- 同一方法连续失败两次就停下来分析根因，换思路，而不是继续微调。
5. 端到端真实验证
单元测试之外，在接近真实的环境做端到端验证：触发操作 → 检查副作用（数据库记录、文件产出、外部状态），确认改动真的生效，而不仅是"代码看起来对"。
6. 复用既有约定，一处修复全局受益
新功能优先沿用项目既有组件、约定与模式，而非另起炉灶。把修复做在共享组件/工具层，让所有调用方一起受益，而不是到处贴补丁。
7. 明确给 AI 的协作偏好
开工前把稳定偏好讲清楚，例如：
- 回复与文档使用的语言；
- "简单改动直接改、复杂设计先给方案确认"；
- 哪些逻辑禁止交给大模型；
- 命名/格式/金额展示等约定；
- 测试数据必须清理、长任务分批推进等流程要求。
AI 在明确边界内自主推进效率最高。
8. 规避工具与环境陷阱
- 命令行处理多字节文本（如中文）易被截断/乱码时，改用写临时文件 + 脚本读取等稳健方式。
- 复杂逻辑放进脚本（
node -e/python3 -c等），避免在 shell 里拼脆弱的一行命令。 - 编译型/需构建的后端，改完务必重新构建再重启进程，否则跑的是旧产物。
- 注意存储层对特殊字符的限制（如某些数据库不接受特定控制字符），入库前编码、读出时解码。
三、工程实践沉淀
- 数据库变更迁移化：所有 schema 变更走可重放、可回滚的迁移脚本，保证各环境一致。
- 配置与密钥惰性读取：运行期再读取密钥/配置，避免模块加载时固化导致开关失效；密钥不入库，放进被忽略的本地配置。
- 统一审计中间件：用一处中间件集中记录写操作与关键读操作（操作人、角色、对象、动作、结果、耗时、来源），跳过高频轮询端点避免日志噪音。
- 稳定 ID 关联 + 数据隔离：记录之间用稳定 ID 关联、界面实时解析为可读名称；按角色/归属做行级数据隔离。
- 质量内建：把可访问性、对比度、一致性等检查纳入自动化测试，由统一的设计体系保证 UI 一致。
- 一键部署：把构建、上传、迁移、重启、健康检查封装成一条命令，降低发布风险与心智负担。
四、优化建议（通用清单）
工程与质量
- 端到端回归纳入 CI：补一条主链路 E2E，作为"改 A 坏 B"的防线。
- CI 门禁：类型检查 + 静态检查 + 测试全绿才可合并/部署；发布脚本前置测试闸门。
- 测试分层与解耦：高频变动模块按功能区拆分测试，降低脆性；区分单元/集成/E2E 各司其职。
- 性能前置：列表服务端分页 + 关键查询建索引；大数据量时前端虚拟滚动。
架构与可维护性
- 及时拆分巨型文件：单文件过大时按职责/资源域拆分，降低认知负担与合并冲突。
- 减少隐式依赖：避免依赖框架的隐式缓存/副作用，关键数据显式获取一次并复用。
- 关键语义文档化：易被误解的业务语义（如可累加 vs 幂等、历史值 vs 当前值）写入设计文档，防止重复踩坑。
AI 层
- AI 输出做 schema 校验 + 置信度阈值：结构化校验大模型产出，低置信走兜底；把调用耗时/降级率纳入监控。
- 提示词与模型版本治理：集中管理、版本化 prompt 与模型名，便于灰度与回滚。
- 数据飞轮：把"预测 vs 实际"的偏差、人工修正反哺给 AI 的少样本示例，持续提升质量。
安全与合规
- 认证用成熟方案：优先用成熟库而非自实现，支持密钥轮换、较短有效期 + 刷新令牌。
- 密钥治理与备份演练：确认密钥不入库；定期演练备份恢复，而不仅是备份。
- 会话失效策略：无状态令牌如需"立即失效"，引入短期令牌 + 服务端黑名单/版本号。
五、可复用的"黄金法则"清单
- 决策逻辑确定性纯函数化，AI 只做语言层，二者严格隔离。
- 先规格（需求 / 设计 / 正确性属性）后代码，规格是地面真值。
- 核心逻辑写属性测试，而不仅是样例测试。
- 小步改动 + 每批"类型检查 + 测试"验证 + 独立提交。
- 根因优先，拒绝表面打补丁。
- 改完在接近真实的环境做端到端验证（含副作用）。
- 强类型 + 迁移化 schema + 统一审计，让系统可回归、可审计、可解释。
- 开工前对齐协作偏好与边界，让 AI 在明确约束内自主推进。
本文为通用方法论，可随团队实践持续补充。