---
name: core-engineering-principles
scope:
  - '*'
products:
  - '*'
id: ka-hard-rule-核心工程执行原则
asset_kind: governance_rule
lifecycle_status: active
authority: canonical
owner_mechanism_id: mc-core-engineering-principles
routes: ['*']
primary_triggers:
  - 核心工程执行原则
secondary_triggers: []
negative_triggers: []
priority: P0
specificity: 5
consumes:
  - mc-all-mechanisms
hard_blocks:
  - 中文策略违反
  - 非必要英文
fallback: manual_required
required_evidence:
  - core_principles_report
version: 1.1.0
last_reviewed: '2026-06-01'
type: governance_rule
when: 核心工程执行原则
stages: ["*"]
---

# 核心工程执行原则

> 适用: 所有 code_execution / multi_stage_plan / single_artifact 路由。

## 四条原则

### 原则一: Think Before Coding — 编码前先思考

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

**必须做到:**
- 暴露阻塞性困惑，不假装理解
- 区分可推断事实、假设、需要用户确认的问题
- 只问最小阻塞问题，不把非阻塞细节抛给用户
- 把 material 级不确定记录为 assumption，不得假装确定

**硬失败条件:**
- 缺少必要输入却开始写代码
- 写入 scope 不明确却修改文件
- 外部副作用权限不明确却执行命令
- 把未知事实写成确定结论
- 隐藏需要用户确认的业务口径

**不确定性分级:**
- `blocking`: 不问不能继续（写入路径、业务口径、外部副作用授权、破坏性操作）
- `material`: 可先推进，但必须记录假设和风险（UI 文案偏好、非关键默认配置）
- `minor`: 可合理默认，但在结果里说明（文件命名细节、无风险排序偏好）
- `non_blocking`: 不打断用户，不影响当前执行

### 原则二: Simplicity First — 简单优先

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

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

**硬失败条件:**
- 为局部问题引入无必要新依赖
- 为简单修复新增大范围架构层
- 没有用户目标支撑却扩展公共 API/配置/registry
- 使用复杂方案绕过已有简单本地模式

**不是"少做":**
- 不写测试不叫简单
- 不接主链路不叫简单
- 不处理边界不叫简单
- 不做必要错误处理不叫简单
- 不建必要抽象不叫简单

**minimum_sufficient_solution 必须满足:**
- 满足用户目标
- 接入真实路径
- 覆盖关键失败路径
- 有验证证据
- 没有不必要抽象/依赖/公共 API 扩张

### 原则三: Surgical Changes — 精准修改

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

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

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

**允许的必要联动修改:**
- 主链路接入必须修改入口文件
- 类型变化必须修改调用方
- schema 变化必须修改 model/query/API
- 验证失败需要修改测试或 fixture
- contract 状态变化必须修改 registry、diagnostic、verification 和相关测试

### 原则四: Goal-Driven Execution — 目标驱动执行

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

**必须做到:**
- 明确目标和验收标准
- 禁止"功能正常""看起来没问题"等模糊成功标准；必须写出已执行验证和剩余风险
- 输出未验证项和人工确认项

**硬失败条件:**
- 没有可验证目标就开始实现
- 没有 VerificationPlan 就标记完成
- 未执行验证却输出"全部通过"
- 验证失败仍进入 completed / delivery_ready
- 隐藏未验证项

## 原则冲突优先级

```
安全/权限/隐私 > Goal-Driven Execution > Think Before Coding > Surgical Changes > Simplicity First
```

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

## 反规避规则

四原则必须由证据证明，不接受 AI 自述。

伪满足示例:
- 写一句"已思考清楚"，但没有输入、假设、目标证据
- 说"保持简单"，但实际新增大抽象
- 说"只改必要文件"，但 diff 里有无关变更
- 说"验证通过"，但没有真实 evidence
- 把未执行验证写成"建议验证"后仍标记完成
- 把用户没确认的业务口径写成事实

硬规则:
- 自述不能代替 ClarificationNeed / AssumptionRecord / GoalDefinition / VerificationEvidence
- required 原则失败不能进入 completed
- 验证失败必须进入 repair_reverify 或 manual_required
- 不能用 advisory 结果覆盖 required 失败
