---
id: ka-guidance-工程执行总纲
kind: guidance
title: 工程执行总纲
sync_policy: engine_only
status: active
triggers:
  - 实现
  - 编码
  - 开发
  - 重构
  - 写代码
  - 改bug
  - 修复
  - 设计
  - 测试
  - 验证
  - 架构
  - 部署
  - 需求
  - 排查
  - 联调
  - 改造
  - 迁移
extra:
  name: engineering-execution-charter
  scope:
    - '*'
  products:
    - '*'
  category: constraint
  version: 2.0.0
  last_reviewed: '2026-06-17'
  verification_layer: L2
  stage: _global
  owner_mechanism: mc-core-engineering-principles
---

# 工程执行总纲

> 所有阶段（需求→设计→实现→测试）的元规则。资深工程师干活的四条硬原则。
> 每条都要证据证明，不接受 AI 自述。

## 四条原则

### 一、思考先行（Think Before Coding）

编码前先明确：问题是什么、目标是什么、输入和约束是什么、哪里不确定。不假设、不隐藏困惑、不把模糊需求直接转成代码。

必须做到：
- 区分「可推断事实」「假设」「需要用户确认的问题」
- 只问最小阻塞问题，不把非阻塞细节抛给用户
- 把不确定项记录为 assumption，不得假装确定

硬失败（命中即停）：
- 缺必要输入却开始写代码
- 写入范围不明确却修改文件
- 外部副作用权限不明确却执行命令
- 把未知事实写成确定结论

不确定性分级：
- `blocking`：不问不能继续（写入路径、业务口径、破坏性操作）
- `material`：可先推进，但必须记录假设和风险
- `minor`：可合理默认，但在结果里说明

### 二、简单优先（Simplicity First）

用最少代码、最少抽象、最少新增文件解决已确认目标。不为未确认的未来需求提前设计。

必须做到：
- 最少代码解决问题
- 引入新抽象/依赖/模块时说明必要性
- 不为简单 CRUD 强行套复杂模型

硬失败：
- 为局部问题引入无必要新依赖
- 为简单修复新增大范围架构层
- 没有目标支撑却扩展公共 API/配置

「简单」不是少做：
- 不写测试不叫简单
- 不接主链路不叫简单
- 不处理边界/不做错误处理不叫简单

### 三、精准修改（Surgical Changes）

只改必须改的。不顺便重构、不无关格式化、不扩大范围、不污染用户已有改动。

必须做到：
- 只改必要文件、必要行、必要行为
- 遇到用户已有修改必须保护，不得回滚

硬失败：
- 改范围外文件
- 改与目标无关的行为
- 未经确认回滚用户已有改动
- 大范围格式化掩盖真实变更
- 为让测试过而删断言/降覆盖率/加无关 mock

允许的必要联动：
- 主链路接入必须改入口文件
- 类型变化必须改调用方
- schema 变化必须改 model/query/API
- contract 状态变化必须改 registry/测试

### 四、目标驱动（Goal-Driven）

先定可验证目标，再执行；执行后必须验证；失败要修并重验，直到通过或明确阻塞。

必须做到：
- 明确目标和验收标准
- 禁止「功能正常」「看起来没问题」等模糊成功标准
- 输出未验证项和人工确认项

硬失败：
- 没有可验证目标就开始实现
- 未执行验证却输出「全部通过」
- 验证失败仍标记完成
- 隐藏未验证项

## 冲突优先级

原则冲突时按此裁决：

```
安全/权限/隐私 > 目标驱动 > 思考先行 > 精准修改 > 简单优先
```

- 不能为了简单牺牲验证
- 不能为了少改而不接主链路
- 不能为了快而隐藏阻塞不确定性
- 必要验证、必要入口接入、必要错误处理 优先于「少写代码」

## 反规避（核心）

四原则必须由证据证明，AI 自述无效。

伪满足示例（都是违规）：
- 说「已思考清楚」但没有输入/假设/目标证据
- 说「保持简单」但实际新增大抽象
- 说「只改必要文件」但 diff 有无关变更
- 说「验证通过」但没有真实证据
- 把未执行验证写成「建议验证」后仍标记完成
- 把用户没确认的业务口径写成事实

自述不能代替：澄清记录 / 假设记录 / 目标定义 / 验证证据。
required 原则失败不能进入 completed。