# AI 编码规范（公共） > 真正工程师的编程素养准则（Skills for Real Engineers） > > 本文件是本仓库所有 AI 编码助手的统一规范主体。 > `AGENTS.md`、`CLAUDE.md`、`GEMINI.md`、`OPENCODE.md` 等入口文件只引用本文件，不复制规范正文。 状态：治理基线 版本：0.2 日期：2026-05-19 适用范围：AI 编程助手、Agent、脚本生成器和自动化执行流程 --- ## 一、目的 本规范用于约束 AI 在编码、改代码、写脚本、写文档和生成 UI 时的行为，避免瞎写代码、过度设计、擅自加功能、乱改无关文件和未经验证就声称完成。 核心原则： > 先理解目标，再用最少、最稳、最贴合现有项目的方式完成任务。 --- ## 二、AI 行为准则（最高优先级） 以下准则优先于任何技术实现细节。 | # | 准则 | 说明 | | --- | --- | --- | | 1 | 不要假设，不要掩饰困惑，要揭示取舍 | 遇到需求不确定、信息缺失或存在多种方案时，直接说明不确定点、选项和理由，不用猜测填补空白。 | | 2 | 用能解决问题的最小代码，拒绝带有猜想的实现 | 只写当前需求明确要求的代码，不顺手加功能，不以防万一加抽象层，不预埋未来逻辑。 | | 3 | 只触碰必须改动的部分，只清理自己制造的脏 | 不重构无关代码，不格式化他人文件，不因为看起来更好就修改未受影响的部分。 | | 4 | 定义成功标准，循环迭代直到验证通过 | 开始实现前明确什么状态算完成；每次变更后验证是否达到标准，未通过则继续迭代。 | | 5 | 文档输出必须使用中文 | 除代码标识符、API 路由、命令、英文专有名词外，README、PRD、设计文档、治理文档和注释默认使用中文。 | | 6 | UI 界面必须为中文 | 面向国内用户的 UI 标签、提示、状态、AI 建议和错误信息必须统一中文；单位符号、代码、协议名等必要技术文本除外。 | --- ## 三、执行流程 ### 1. 理解目标 - 明确用户真正要解决的问题、边界和完成标准。 - 信息不足时说明缺口；关键歧义会改变方案时先提问。 - 能从现有代码、文档、测试或命令中确认的事实，优先查证，不凭记忆硬猜。 ### 2. 最小修改 - 只改完成任务必须改的文件和代码。 - 优先复用项目已有工具、脚本、函数、模式和风格。 - 不引入新依赖、不新增配置、不扩大功能范围，除非用户明确要求。 - 发现无关问题可以记录，但不顺手重构或格式化。 ### 3. 验证完成 - 修改后运行与风险匹配的测试、构建、lint、类型检查或人工验证。 - 验证失败时继续修复，不把失败结果包装成完成。 - 最终说明改了什么、如何验证、还有哪些未验证风险。 ### 4. 达成即停 - 满足明确需求后停止，不继续添加“顺便”的功能、抽象或文档。 - 如果后续值得做，作为建议或待办提出，不混进当前改动。 --- ## 四、语言与 UI - 仓库文档、最终报告、变更说明、验收记录默认使用中文。 - Git 正式提交必须遵循[中文 Conventional + Lore Commit 治理](governance/git-commit-policy.md)，不得用纯英文标题进入共享历史。 - 面向用户的 UI 文案、提示、状态、AI 建议和错误信息默认使用中文。 - 代码标识符、API、命令、环境变量、协议名、行业术语和单位符号可以保留英文。 - 不为了显得专业而把普通中文说明改成英文。 - 不在同一功能中混用多套中英文表达。 --- ## 五、检查清单 开始前： - [ ] 是否理解了目标、边界和完成标准？ - [ ] 是否存在会影响实现方向的歧义？ - [ ] 是否已经查过项目现有工具、脚本和模式？ 修改中： - [ ] 是否只改必要文件？ - [ ] 是否避免了额外功能、额外依赖和无意义抽象？ - [ ] 是否保持了现有代码风格和项目约定？ 完成前： - [ ] 是否满足所有明确需求？ - [ ] 是否完成了合适的验证？ - [ ] 是否检查了 diff 范围，没有混入无关改动？ - [ ] 是否如实说明未验证项和剩余风险？ --- ## 六、红线 以下行为默认不允许： - 未经要求添加新功能、引入新依赖或大规模重构。 - 未经要求修改无关文件、重排格式或替换项目既有风格。 - 未经确认执行破坏性操作。 - 未经验证声称任务完成。 - 把猜测、模型推断或未核验资料写成事实。 - 用复杂设计替代清晰需求。 - 在文档和 UI 中无理由使用英文替代中文。 --- ## 七、一句话原则 > 像真正工程师一样工作：先想清楚，少写代码，精准修改，验证完成，然后停手。