---
id: ka-guidance-工程纪律
kind: guidance
title: 工程纪律
sync_policy: engine_only
status: active
triggers:
  - 命名
  - 注释
  - 职责
  - 错误处理
  - 异常
  - 日志
  - 代码风格
  - 实现
  - 编码
  - 写代码
extra:
  name: engineering-discipline
  scope:
    - '*'
  products:
    - '*'
  category: constraint
  version: 1.0.0
  last_reviewed: '2026-06-17'
  verification_layer: L2
  stage: _global
  owner_mechanism: mc-detail-discipline
---

# 工程纪律（基本功）

> 合并命名/注释/单一职责/错误处理/日志的基本要求。这是代码质量的底线。
> 吸收旧的「工程纪律」「细节纪律」「通用机械条款」「代码注释与日志契约」「命名」等碎拆文件。

## 命名

- 表达真实含义，禁止含糊/误导/过度缩写/无意义命名
- 好命名让人少看注释也能懂
- 命名和行为必须一致（叫 validate 就真的校验，别混着干别的）

## 注释

- 解释**为什么**这样做、业务约束、历史原因、边界、风险
- 不复述代码（`// 给 i 加 1` 是废话）
- 代码注释、日志消息、用户可见错误提示一律简体中文，技术术语/标识符保留原文

## 单一职责

- 一个函数只做一类事
- 一个函数同时做参数校验+权限判断+数据查询+状态计算+写入+发消息+记日志 → 拆分
- 单文件/单类职责清晰，避免上帝对象（>20 字段考虑拆分聚合根）

## 错误处理

- 禁止空 catch（至少记日志，不得静默吞异常）
- 错误信息说清楚：哪步失败、关键参数、可能原因、下一步怎么做
- 用户可见错误用中文；日志用中文，标识符保留原文

## 日志

- 统一走 logger（`userInfo`/`userWarn`/`userError`/`debug`/`internalWarn`），禁止 `console.log/error/warn` 直接调用
- 关键路径有可观测日志，便于排查
- 敏感信息不得进日志（密钥、token、个人隐私）

## 数据写入边界

- 不得向 `.soloforge/tasks/`、`.env`、`.git/`、`node_modules/` 写入（安全底线）
- 写文件用原子写，避免半写状态