“超级个体” 培养计划

规范原文

# AGENTS

本文档定义当前工作区的通用开发约束，适用于本目录下各项目及后续新增项目。

若当前工作目录或其上层存在更近的 `AGENTS.md`、`README`、`CONTRIBUTING`、设计文档或明确任务说明，按以下优先级执行：

1. 离当前工作目录最近的 `AGENTS.md`
2. 当前仓库内的 `README`、`CONTRIBUTING`、计划文档、设计文档
3. 本全局 `AGENTS.md`
4. 通用默认习惯

若规则冲突，优先遵循更近的规则，并记录冲突点、处理依据和影响范围。

---

## 1. 基本原则

- 先阅读当前目录及上层可见的 `AGENTS.md`、`README`、`CONTRIBUTING` 和相关设计文档。
- 保持改动克制，优先小步提交、局部修改、最小可行修复。
- 不擅自引入新生产依赖、修改 CI、调整基础目录结构，除非任务明确要求。
- 优先复用现有模块、工具函数、测试模式和项目约定，避免平行造轮子。
- 结论尽量基于代码、日志、测试结果或文档证据，避免凭感觉判断。

---

## 2. 开始编码前

- 对复杂或多步骤任务，先给出简短计划再实施。
- 若关键边界不清楚，先说明当前理解、关键假设和待确认问题。
- 不确定性不阻塞主路径时，可基于明确假设继续推进，但要写清假设。
- 开始改动前先确认影响范围：
  - 代码路径
  - 配置
  - 接口
  - 数据结构
  - 存储格式
  - 权限边界
  - 并发行为
  - 部署行为
- 对高风险任务，先明确最小闭环，避免范围失控。

---

## 3. 排查与调试

遇到非平凡问题时，遵循“观察 -> 假设 -> 实验 -> 结论”的流程。

- 先记录现象和复现条件：
  - 报错信息
  - 输入条件
  - 触发步骤
  - 环境差异
  - 预期行为
  - 实际行为
- 明确区分“已知事实”和“个人推测”。
- 在正式修复前，列出候选根因，并说明：
  - 支持证据
  - 冲突证据
  - 最小验证办法
- 实验遵循单变量原则，一次只验证一个假设。
- 根因未确认前，不做大范围猜测式重构，不叠加多个未经验证的补丁。
- 根因确认后，再实施正式修复，并补对应回归测试。
- 调查结论应回填至现有计划、设计或问题记录文档；必要时新增 `DEBUG.md`。

---

## 4. 实现要求

- 保持与项目既有风格一致，包括命名、目录组织、错误处理、日志风格和配置方式。
- 优先解决根因，不做仅掩盖症状的表层修补。
- 涉及接口、数据结构、持久化格式、并发、权限边界时，主动评估兼容性和副作用。
- 修改公共模块时，优先评估对调用方的影响；必要时补最小兼容层或迁移说明。
- 控制实现复杂度，能局部解决的问题，不轻易上升为系统性重构。
- 非任务必要，不顺手修复无关问题；若发现额外问题，记录即可。
- 调试代码、临时脚本、一次性兼容逻辑应在任务结束前清理，或明确标注用途和清理条件。
- 错误处理应沿用项目既有约定，不随意创造新语义。
- 若无法一次彻底解决，优先交付清晰、可验证、可回退的阶段性最小方案，并说明剩余风险。

---

## 5. 测试与验证

- 对行为变更、缺陷修复和高回归风险改动，优先补复现用例或对应测试。
- 遵循仓库已有测试框架和目录约定，不额外引入新的测试体系。
- 测试尽量覆盖：
  - 正常路径
  - 边界条件
  - 已知失败路径
  - 本次修复对应的回归场景
- 完成改动后运行相关验证，如 `test`、`lint`、`typecheck`、`build` 或直接复现验证。
- 若影响面较大，不只验证改动点，还应补一层受影响路径验证。
- 若无法运行验证，必须说明：
  - 无法运行的原因
  - 当前风险
  - 建议的后续验证方式
- 不以“理论上应该正确”代替测试结论；测试失败时，不得直接宣称完成。

---

## 6. 文档要求

- 对值得沉淀的需求实现、架构决策变更或重要问题调查，及时回填文档。
- 文档重点记录：
  - 决策
  - 原因
  - 验证结果
  - 未解决风险
  - 后续事项
- 文档应服务于维护、协作和追溯，不写琐碎流水账。
- 若实现偏离原方案，应记录偏离原因、偏离内容和影响范围。
- 文档应描述当前实际实现，而不是过时方案。

---

## 7. 安全要求

- 不输出、提交或扩散密钥、凭据、PII 或生产环境敏感配置。
- 删除、迁移、批量重写、权限调整、数据库变更、批处理脚本等高影响操作，先明确风险、影响范围和回退方式。
- 对生产数据、状态性资源和外部系统写操作保持保守；不确定时优先只读、演练、沙箱或局部验证。
- 发现设计缺陷时，不静默绕过，应说明问题、影响范围和备选方案。
- 不伪造验证结果，不隐瞒失败，不把未经验证的猜测表述为事实。

---

## 8. 变更纪律

- 单次任务只交付与目标直接相关的改动，控制 diff 规模，降低审查和回滚成本。
- 每个改动都应能说明必要性，无法说明必要性的改动默认不做。
- 若需分阶段推进，应明确区分：
  - 本次已完成内容
  - 暂不处理内容
  - 建议下一步
- 对可逆性差的改动，如数据迁移、接口语义变更、批量替换，先给出回退策略再落地。
- 高风险任务优先采用“先兼容、再切换、后清理”的演进方式。

---

## 9. 推荐目录约定

每个独立项目原则上按以下结构组织：

- `frontend/`：前端页面、组件、样式、前端数据访问逻辑
- `backend/`：后端接口实现、接口契约、通用模块
- `config/`：本地配置、规则文件、模板、映射表
- `data/`：固定输入样例、测试样例、静态示例数据
- `runtime/`：运行期输出、隔离测试结果、日志、错误快照
- `scripts/`：独立执行脚本、测试脚本、迁移脚本、排查脚本
- `launcher/`：启动器相关文件

约束：

- 不把后端逻辑直接写进前端目录。
- 不把配置文件放进前端可见页面或静态资源目录。
- 不把运行日志写入源码目录中的业务文件旁边。
- 不在根目录长期保留临时调试文件或临时导出文件。

---

## 10. 命名规范

- 命名必须表达业务含义，避免空泛、模糊和无意义超长命名。
- 同一概念在全项目内应保持一种主命名。
- 文件命名优先使用 `kebab-case`。
- 变量、函数、对象字段优先使用 `camelCase`。
- 常量使用全大写下划线风格，仅用于真正稳定的固定值。
- 函数名应体现动作和结果，优先使用以下模式：
  - `loadXxx`
  - `buildXxx`
  - `normalizeXxx`
  - `extractXxx`
  - `assertXxx`
  - `createXxx`
  - `executeXxx`
- 避免使用语义不清的命名，如 `handle`、`process`、`runAll`、`doStuff`、`fixData`。

---

## 11. 接口与数据结构

- 每个接口应有稳定的接口标识、输入、执行过程说明和输出结构。
- 对外入参应与业务概念一致，不混入调试字段。
- 必填字段必须前置校验，归一化规则应固定、可复用、可追踪。
- 中间结果只服务当前流程，不直接暴露给前端。
- 输出结构优先保证稳定，再追求内容完整。
- 对可能缺失的字段，应补齐空结构或默认值，而不是随意删字段。
- 增加字段可以，删除字段或修改字段名必须先确认影响范围。
- 字段含义变化时，必须同步更新文档和调用方说明。

---

## 12. 配置与规则文件

- 所有业务配置优先放入配置文件，不直接写死在业务流程或页面中。
- 代码应通过统一配置加载函数读取配置，不在多个文件重复拼接路径规则。
- 规则文件、模板文件、映射表应有稳定结构，供代码明确读取。
- 读取结构化文件时，必须依赖明确字段，不依赖人工约定。

---

## 13. 模块拆分与代码组织

- 每个模块只负责一类职责，例如：
  - 输入校验与归一化
  - 数据解析
  - 规则读取
  - 外部依赖调用
  - 输出归一化
  - 日志记录
  - 审核与重试
- 编排器只负责流程编排，不堆积大量细节实现。
- 模型输出、外部输入、表格读取结果等不稳定数据，必须先归一化再使用。
- 校验失败应抛出明确错误，错误信息应能帮助定位具体字段。
- 逻辑组织优先遵循：
  - 先校验
  - 再解析
  - 再调用依赖
  - 再归一化
  - 最后输出
- 重试逻辑必须显式记录轮次、对象、原因和最终结果，不做静默无限重试。

---

## 14. 前后端职责

### 前端

- 负责展示、筛选、分页、触发动作和结果呈现。
- 不负责长期存放后端业务规则、模板或敏感配置。
- 页面文案、字段展示和交互逻辑应与当前业务命名保持一致。
- 分页、筛选、加载状态、空状态应清晰可解释。

### 后端

- 每个接口应有独立服务入口。
- 共享能力统一沉淀到公共模块。
- 输出应为前端提供稳定、可消费的数据结构，避免前端二次猜测。
- 外部依赖调用前后应有日志，失败时应有明确错误返回和错误记录。

---

## 15. 日志与错误处理

- 真实测试、隔离测试和运行期日志统一写入 `runtime/`。
- 日志按接口或任务分目录存放，目录名建议包含时间戳和业务标识。
- 关键执行步骤和错误原因应可追踪。
- 结构化日志应写入独立文件，便于回放和定位。
- 错误信息应尽量包含：
  - 失败步骤
  - 失败原因
  - 输入快照
  - 错误堆栈
  - 失败阶段
- 避免仅输出“执行失败”这类无效错误。

---

## 16. 完成标准

满足以下条件后，才可视为任务完成：

- 代码改动与任务目标一致
- 受影响路径已做适当验证，或已明确说明为什么暂未验证
- 关键假设、限制、风险和后续建议已说明清楚
- 已检查并尽量控制兼容性、副作用和影响范围
- 已补充必要测试，或已说明缺失测试的原因与风险
- 已同步必要文档
- 未引入与任务无关的改动
- 产出对后续维护者可理解、可验证、可接手

---

## 17. 维护规则

- 新增功能、接口、页面或脚本时，先遵循本文档，再决定目录、命名、日志和文档写法。
- 若现有规则已不适配，应先更新本文档，再进行大规模实现调整。
- 本文档一旦更新，后续开发默认按最新版本执行。