---
id: ka-guidance-编码纪律
kind: guidance
title: 编码纪律
sync_policy: engine_only
status: active
triggers:
  - 实现
  - 编码
  - 写代码
  - 开发
  - 编码阶段
  - 切片执行
  - 后端实现
  - 前端实现
extra:
  name: coding-discipline
  scope:
    - '*'
  products:
    - '*'
  category: procedure
  version: 1.1.0
  last_reviewed: '2026-06-22'
  verification_layer: L2
  stage: build
  domain: build
  owner_mechanism: mc-coding-readiness
---

# 编码纪律：怎么把代码写对

> 吸收旧的「编码阶段执行」「编码就绪审查」「编码质量」「切片执行纪律」「防御性编码」。
> 基本功（命名/注释/单一职责/错误处理）见 [[工程纪律]]，不重复。

## 高影响实现：先研讨边界再动手

当实现跨多个发布单元、包含不可逆数据变更、存在高风险兼容影响或用户尚未确认取舍时，写代码前先确认顺序、边界和风险，把结论写入切片计划或对应决策记录。

- 研讨重点：切片实现顺序、跨切片共享代码先沉淀、风险切片先行验证
- 低风险、可逆且已有明确契约的修改直接按最小范围推进，不为凑记录增加会议。

## 工程骨架：首个切片建多工程目录（涉及多端时）

需要新增工程时，按架构端清单和 intent.yaml `projects` 创建真实工程目录。目录名、源码布局、构建文件和是否独立发布均来自项目声明或所选技术栈，不套示例目录。

- 工程目录结构 = 架构 第6.3节 端清单 + intent.yaml `projects`（build scope `allowed_paths` 据此放行）
- 只为真实独立工程提供所需的忽略和构建配置；共享仓库级配置可以复用时不重复制造文件。
- brownfield 先尊重现有布局，通过 project map 声明偏离；目录迁移必须先做兼容性评估。

## 前端骨架先行（涉及 FE-* 端时）

涉及前端端时，先建立当前首个可交付页面真正需要的运行入口、路由、状态和 API 边界。只有多个页面确实共享且能立即被消费时才抽公共层，不为“以后可能用”预建空壳。

- 共享层必须有当前消费者；没有消费者的抽象视为半成品。
- API 调用边界遵循现有前端架构和可测试性要求，不用固定文件名或层名冒充解耦。
- Vue3/uni-app 等无内置脚手架的技术栈，配自定义模板合同（`config.scaffold.contracts`）

## 前端组件通用化封装（涉及 FE-* 端时）

同形态第三处出现前抽通用组件（表格页/表单弹窗/筛选栏/状态标签/操作列等）——逐页复制 markup 是漂移与不一致的温床。

- 通用组件 = props/slots/emits 驱动 + 无业务耦合（数据获取留在页面/容器层）；页面级差异不上提。
- 抽取时机：第二处复制先标注，第三处出现时必须抽；抽出后消费点全部切换并验证。
- 通用组件落项目的组件目录并注明适用场景；孤儿组件（无消费者）视为半成品删除。

## 前端 UI 实现须参照原型说明（涉及 FE-* 端时）

涉及前端页面时，UI 实现必须参照 project map 解析到的对应原型说明，不得脱离素材凭空生成。

- 设计令牌（色彩/间距/字体/圆角）取自原型说明「设计令牌」章节，禁止凭感觉硬编码色值/间距
- 页面布局、组件结构、数据绑定参照原型说明「页面布局树」「组件数据绑定」章节
- 交互流转、组件视觉状态参照原型说明对应章节
- 原型说明缺失时先按当前 project map 和 prototype skill 补齐；没有素材则向用户明确缺口，不得自由发挥后宣称符合
- **边界**（确定性边界原则）：原型说明的提取（图片/源码/html→结构化）与 UI 贴合度都是 AI 视觉判断、非确定性；验证器只检查可确定的引用和结构，视觉一致性靠局部自查与 [[UI视觉验收纪律]] 人工验收留痕

## 实现前：先列改动清单（精准修改）

动手前明确（[[工程执行总纲]] 精准修改）：
- 要改哪些文件、改什么行为
- 主链路入口在哪、必须接入（不接入=孤岛）
- 类型/schema 变化的必要联动调用方
- 不改什么（范围外文件不动）

## 实现中：不写半成品

- 不留空函数体、静默 catch 或无责任人的 TODO 占位
- 关键业务取舍按项目语言约定解释 why；日志采用项目事件命名和结构化字段约定
- 错误处理：禁止静默吞异常，错误信息说清哪步失败+原因+下一步
- 事务：涉及多个必须原子一致的写入时，按当前框架明确事务或补偿边界；单写入、事件驱动或非事务存储不套固定注解
- 边界：空数据、null、超长、并发、重复提交都要处理

## 类型安全（TS）

- 禁 `as any` 绕类型（TS-Q01），禁 `@ts-ignore/@ts-nocheck`（TS-Q02）
- 禁 `==`/`!=`，用 `===`/`!==`（TS-Q03）
- 禁 `var`，用 `let`/`const`（TS-Q04）

## 接口契约先行

- 接口契约先于实现（避免前端等后端）
- 后端接口有 OpenAPI 文档
- 每完成一个子模块及时联调，不要全做完才联调

## 防御性编码

- 外部输入一律校验（类型/范围/权限）
- 存在重试、重复投递或用户重复提交时明确幂等语义；不适用时无需制造幂等键
- 跨系统调用考虑超时/重试/熔断（[[安全加固]]）

## 反规避

- 空函数体/TODO 占位 = 半成品（违规）
- 不接入主链路 = 孤岛（违规）
- 静默 catch = 吞异常（违规）
- 为了过测试删断言/降覆盖率（违规，[[工程执行总纲]] 精准修改硬失败）