# 前置思考与沟通准则

> **适用范围**：任何「先理解、再动手」的协作任务（编码、运维、文档、数据分析等）。
> **关于示例值**：文中的目录名（如 `.venv`）、行数、次数、路径都是**示例**，用于说明原则；项目有自己的约定时，**一律以项目约定为准**。建议把可变的目录名 / 阈值 / 命令集中写进项目的「参数约定」或环境配置，本文只保留不随项目变化的判断原则。

---

## 一、前置思考与沟通准则

**核心原则：先想清再动手，不确定必澄清，绝不擅自决策。**

1. **编码前完成思考闭环**
   - 不做无依据假设，不回避认知困惑，明确方案利弊权衡后再启动编码；
   - 动手前主动陈述所有前置假设；存在信息缺失或不确定性时，立即暂停并提问澄清。
2. **多解读场景不私自选择**
   - 若需求存在多种合理解读，需完整列出所有解读方向与差异点，不得擅自选定某一种执行。
3. **主动反馈更优方案**
   - 若存在更简洁、更低成本的实现路径，主动说明并提出建议；对明显不合理的需求，可提出反对意见并阐述理由。
4. **模糊问题标准化确认**
   - 遇到定义模糊、边界不清或拿不准的问题，整理为清晰的问答形式确认，消除歧义后再推进。

---

## 二、极简设计原则（简洁至上）

**核心原则：YAGNI（够用即止），拒绝过度设计。**

1. **最小化实现**：用最少的代码满足需求，不做无根据的推测与扩展。
2. **不做额外功能**：不添加任何需求范围外的功能、特性与优化。
3. **拒绝过早抽象**：不为一次性使用的代码做分层、封装与抽象设计。
4. **不做冗余灵活性**：未被明确要求的「灵活性」「可配置性」「扩展性」均不实现。
5. **异常处理有边界**：不对理论上不可能出现的场景做错误处理与防御性编程。
6. **复杂度自检**：若代码量远超合理预期（如本可 N 行实现，却写了数倍于 N 行的代码；N 按项目规模自定），必须重写简化。
7. **专业视角校验**：自问「资深工程师会不会认为这过于复杂」，若答案为是，立即简化。

---

## 三、精准修改规范

**核心原则：最小化改动，尊重存量，权责清晰。**

1. **最小触碰原则**：仅修改与需求直接相关的代码，不扩大修改范围。
2. **不做无关优化**：编辑现有代码时，不擅自「改进」相邻代码的逻辑、注释、格式与命名。
3. **不重构无问题代码**：不对无故障、与当前需求无关的代码进行重构或风格调整。
4. **遵循现有风格**：严格遵循项目既有代码风格与规范，即便与个人编码习惯不同。
5. **存量问题不私自处理**：发现与当前需求无关的无效 / 冗余代码，仅做指出说明，不得私自删除或修改。
6. **自有改动闭环清理**：因本次修改产生的未使用导入、变量、函数等孤岛代码，必须同步清理删除。
7. **需求对应校验**：每一行修改的代码，都必须能直接对应到明确的用户需求点。

---

## 四、目标驱动执行流程

**核心原则：可验证、可追溯，不模糊推进。**

1. **任务转化为可验证目标**
   - 「添加验证」→ 先准备无效输入的验证手段（测试用例 / 复现脚本 / 对照数据），再实现逻辑使其通过；
   - 「修复漏洞」→ 先准备可复现漏洞的验证手段，再修复问题使其通过；
   - 「重构代码」→ 先确认现有测试全部通过，重构后保证测试结果完全一致。
2. **多步骤任务制定执行计划**
   多步骤任务需先输出简短计划，每个步骤绑定明确验证点：

   ```text
   1. [执行步骤 1] → 验证：[校验标准 1]
   2. [执行步骤 2] → 验证：[校验标准 2]
   3. [执行步骤 3] → 验证：[校验标准 3]
   ```

3. **模糊标准必须澄清**
   以「能运行即可」「看着差不多」等模糊表述作为成功标准的需求，必须先澄清为可量化、可验证的标准，否则不推进执行。

---

## 五、代码交付质量标准

**核心原则：可读、可运行、鲁棒性达标。**

1. **关键配置、核心逻辑必须添加清晰注释**，说明设计意图、使用方式与注意事项。
2. **核心功能需附带可直接运行的使用示例**，降低理解与接入成本。
3. **对预期内的异常场景**（入参非法、依赖不可用等）做必要的异常捕获与友好提示。
4. **配置项统一抽离管理**，不硬编码在业务逻辑中；可变值放进配置 / 环境变量 / 常量文件，具体载体按项目约定选择。

---

## 六、Python 环境管理规范

**核心原则：环境隔离，绝不污染全局。**

1. 执行 Python 代码前，先检查项目约定的虚拟环境目录（常见 `.venv`、`venv`，以项目文档为准）。
2. 没有现成虚拟环境时，必须在当前工作目录下创建独立环境；命名遵循项目约定，无约定时用 `.venv`。
3. 所有依赖安装、脚本执行操作，必须在项目虚拟环境内完成，绝对禁止使用全局 Python 环境安装依赖或执行项目代码。
4. 项目使用 conda / poetry / uv / Docker 等其它隔离方式时，按其约定执行，不额外创建 `.venv`。

---

## 七、代码复用与一致性原则

**核心原则：DRY（不要重复自己），兼顾清晰与复用。**

1. 可复用的常量、配置、逻辑片段，仅定义一次，通过变量 / 函数 / 常量引用使用。
2. 禁止多处硬编码相同的数值、字符串、路径等重复内容。
3. 重复出现的逻辑片段统一抽取为公共函数 / 方法，避免复制粘贴式编码。
4. 复用设计以「清晰可读」为前提，不为强行复用而增加不必要的抽象复杂度。