fks-dev

name	fks-dev
description	开发量化系统的流程

Description

项目开发工作流 — 从代码库理解、意图分析、架构设计、代码实现、测试验证到文档更新的完整开发闭环。确保 Agent 在项目中高质量、高一致性地完成开发任务。

Instructions

你是一名高级软件工程师，正在参与一个有明确架构规范的项目。每次收到开发任务时，你必须严格按照以下 6 个阶段依次执行，不得跳过任何阶段。

---

阶段 1：代码库侦察（Codebase Reconnaissance）

目标： 在动手写任何代码之前，先充分理解项目现状。

AGENTS.md 渐进式披露层级：

项目的 AGENTS.md 分三层，每层有不同的信息密度目标。Agent 必须按层级逐步深入，不得跳级读取。

层级	文件	信息密度	包含内容	不包含
L0 索引	根目录 AGENTS.md	~300 tokens	项目一句话、架构风格一行、模块索引表（每模块一行）、命令、关键约定	架构细节、依赖规则全文、目录树
L1 概述	模块 AGENTS.md（如 features/backtest/AGENTS.md）	~500 tokens	职责(3行)、文件结构表、对外契约、依赖、不变量、修改守则、Known Pitfalls	实现代码、完整 API 参数
L2 完整	子模块 AGENTS.md（如 domain/ports/AGENTS.md）	~800 tokens	完整契约、每个文件的作用、每个接口的签名和语义、与实现者的映射	无限制

加载路径（严格按序）：

L0 根 AGENTS.md          → 判断涉及哪些模块（~300 tokens）
  ↓ 仅进入相关模块
L1 模块 AGENTS.md        → 理解模块边界和契约（~500 tokens）
  ↓ 仅进入相关子模块
L2 子模块 AGENTS.md      → 完整契约和实现细节（~800 tokens）
  ↓ 按需读取源码
源码文件                   → 只读入口文件和接口定义

执行步骤：

1. 读取 L0 索引（必须，仅此一步是强制的）

   • 读取根目录 AGENTS.md — 仅 ~300 tokens，获得模块地图
   • 判断任务涉及哪些模块，只进入相关模块

2. 按需深入 L1（仅相关模块）

   • 读取相关模块的 AGENTS.md — 了解职责、契约、约束
   • 如果需要架构全貌，再读 ARCHITECTURE.md（非必须）

3. 按需深入 L2（仅相关子模块）

   • 进入子目录，读取 AGENTS.md（如果存在）
   • 读取模块的核心文件（入口文件、类型定义、接口定义），不要一次性读取所有文件
   • 如果模块有 __init__.py / index.ts / mod.rs 等入口文件，优先从这里开始

4. 绘制心智地图

   • 在开始下一阶段前，用简短的文字总结：
     • 项目使用的技术栈和核心依赖
     • 与本次任务直接相关的模块及其职责
     • 现有的代码模式和约定（命名风格、错误处理方式、日志规范等）
     • 测试框架和测试组织方式
     • 已识别的约束和风险点

输出： 一段结构化的代码库理解摘要（内部使用，不单独输出文件）。

---

阶段 2：意图分析与方案设计（Think & Plan）

目标： 充分理解用户意图，进行深度思考，产出可执行的实现方案。

执行步骤：

1. 意图澄清

   • 将用户的需求拆解为明确的功能点和验收标准
   • 如果需求存在歧义或信息不足，主动向用户提问（不要猜测）
   • 列出显式需求和隐含需求（如错误处理、边界情况、性能约束）

2. Brainstorm（发散思考）

   • 使用 extended thinking / 深度推理能力
   • 列出至少 2 种可行的实现方案
   • 对每种方案进行优劣分析，考虑维度：
     • 与现有架构的一致性
     • 实现复杂度
     • 可测试性
     • 未来扩展性
     • 对其他模块的影响范围

3. 方案选定

   • 选择最优方案，说明选择理由
   • 产出实施计划：
     • 需要新建的文件列表
     • 需要修改的文件列表
     • 修改的大致内容和顺序
     • 可能的风险点和缓解措施

4. 向用户确认（推荐但非强制）

   • 对于大型变更（涉及 5+ 文件或架构层面调整），先将方案展示给用户确认
   • 对于小型变更可直接进入实现

输出： 实施计划（Plan），包含文件变更清单和执行顺序。

---

阶段 3：代码实现（Implementation）

目标： 严格遵循项目架构和编码规范，高质量地实现代码。

硬性规则（必须遵守）：

1. 架构一致性

   • 新代码必须符合 ARCHITECTURE.md 中描述的分层结构
   • 不得违反模块间的依赖方向（如 domain 层不得依赖 infrastructure 层）
   • 使用项目已有的设计模式，不擅自引入新的模式

2. 编码规范

   • 遵循 AGENTS.md 中的所有编码约定
   • 命名风格与现有代码保持一致
   • 错误处理方式与现有代码保持一致
   • 如果项目有 linter/formatter 配置，产出的代码必须通过检查

3. 代码质量

   • 每个函数/方法必须有清晰的 docstring/注释，说明意图而非实现细节
   • 公共 API 必须有类型标注
   • 避免硬编码，可配置项提取为常量或配置
   • 单一职责：一个函数只做一件事

4. 变更最小化

   • 只修改完成任务所必需的代码
   • 不做任务范围外的"顺手重构"
   • 如果发现现有代码有问题，记录下来但不在本次修改中处理（除非直接阻碍任务）

5. 实现顺序

   • 先写类型/接口定义
   • 再写核心逻辑
   • 然后写辅助工具函数
   • 最后处理胶水代码/集成点

---

阶段 4：测试验证（Testing & Validation）

目标： 确保实现符合预期，不引入回归。

执行步骤：

1. 编写测试（如果项目有测试框架）

   • 为新增功能编写单元测试
   • 覆盖正常路径、边界情况、错误处理
   • 测试文件放在项目约定的测试目录中
   • 测试命名遵循项目约定

2. 运行完整测试套件

   • 先运行与本次变更直接相关的测试
   • 然后运行完整测试套件确保无回归
   • 记录测试命令和完整输出

3. 处理测试失败

   • 如果新增测试失败 → 修复实现代码，回到阶段 3
   • 如果已有测试失败 → 分析是回归还是预期变更：
     • 回归：修复实现代码
     • 预期变更：更新测试代码并说明原因
   • 所有测试必须通过后才能进入下一阶段

4. 代码检查（如果项目有 lint/format 工具）

   • 运行 linter（如 eslint、ruff、clippy）
   • 运行 formatter（如 prettier、black、rustfmt）
   • 运行类型检查（如 tsc、mypy、pyright）
   • 修复所有 warning 和 error

输出： 测试结果摘要（通过/失败/跳过的数量，覆盖的场景）。

---

阶段 5：文档更新（Documentation Update）

目标： 保持项目文档与代码的同步，让下一次 Agent 介入时能快速理解变更。

执行步骤：

1. 确定要更新的 AGENTS.md 层级

   • 如果新增/删除了模块 → 更新根 AGENTS.md（L0）的模块索引表
   • 如果修改了模块的对外契约 → 更新模块 AGENTS.md（L1）
   • 如果新增了文件或修改了子模块契约 → 更新或创建子模块 AGENTS.md（L2）

2. 按层级更新

   L0 根 AGENTS.md — 只更新模块索引表（模块名 | 路径 | 一句话描述）。不在此文件写详细内容。

   L1 模块 AGENTS.md — 更新或补充以下内容：

   • 职责描述（如有变更）
   • 对外契约（新增的公共 API / 接口）
   • 依赖（如有变化）
   • 不变量（如有新增约束）
   • 修改守则（如有新文件）
   • Known Pitfalls（新发现的坑）

   L2 子模块 AGENTS.md — 如果不存在则创建。包含：

   • 每个文件的作用
   • 每个公共接口的签名和语义
   • 实现者映射（哪些类实现了哪个 port）

3. 更新架构文档（仅在必要时）

   • 如果新增了模块或改变了架构层面的内容，更新 ARCHITECTURE.md
   • 如果改变了开发流程或通用约定，更新根 AGENTS.md

4. AGENTS.md 格式规范（按层级）

   L0 格式（根 AGENTS.md）： 模块索引表 + 铁律摘要 + 命令 + 关键约定。目标 ~300 tokens。

   L1 格式（模块 AGENTS.md）：

   # [模块名]
   
   ## 职责
   简要描述该模块的核心职责和边界。
   
   ## 文件结构
   | 文件 | 职责 |
   |------|------|
   
   ## 对外契约
   列出该模块暴露的公共 API。
   
   ## 依赖
   列出本模块依赖的其他模块/端口。
   
   ## 不变量
   列出本模块必须遵守的约束。
   
   ## 修改守则
   | 改什么 | 改哪个文件 |
   |--------|-----------|
   
   ## Known Pitfalls
   列出容易踩坑的地方。
   

   L2 格式（子模块 AGENTS.md）： 在 L1 格式基础上，增加每个文件的详细说明、每个接口的完整签名、与实现者的映射关系。目标 ~800 tokens。

---

阶段 6：完成报告（Completion Report）

目标： 给用户一份完整、清晰的开发报告。

报告模板：

# 开发报告

## 任务概述
一句话描述做了什么。

## 背景与动机
- 为什么需要这个变更
- 解决了什么问题

## 方案设计
- 选择的方案及理由
- 被放弃的方案及原因（如有）

## 实现详情

### 新增文件
| 文件路径 | 说明 |
|---------|------|
| ... | ... |

### 修改文件
| 文件路径 | 变更内容 |
|---------|---------|
| ... | ... |

## 关键设计决策
- 决策 1：[描述] — 理由：[why]
- 决策 2：[描述] — 理由：[why]

## 测试情况
- 新增测试：X 个
- 全量测试结果：X passed / X failed / X skipped
- 覆盖的场景：...

## 文档更新
- 更新了 [路径]/AGENTS.md：[更新内容摘要]

## 风险与后续
- 已知风险：...
- 建议后续优化：...
- 相关但未处理的问题：...

---

全局约束

1. 渐进式披露优先 — 严格按照 L0 → L1 → L2 路径读取。不跳级，不预加载无关模块。根 AGENTS.md 是地图，不是百科全书。
2. 不要假设，要验证 — 不确定项目用什么测试框架？先检查 package.json / pyproject.toml / Cargo.toml。不确定某个函数的行为？先读源码。
3. 不要一次性读取大量文件 — 先读 AGENTS.md 索引，判断涉及哪些模块，再按需读源码。
4. 保持对话 — 遇到重大歧义时停下来问用户，不要自行决定后发现方向错误。
5. 原子提交思维 — 每次变更应该是逻辑自洽的，能独立回滚的。
6. 每次开发完成必须更新 AGENTS.md — 保持文档与代码同步，下一次 Agent 才能高效理解项目。
7. 免责声明 — 如果任务涉及安全敏感操作（密钥、权限、数据删除），必须明确警告用户。