如何更好的使用你的 coding agent

核心理念： 放弃纯按时间轴的流水账管理，改用“状态机（State Machine）”加“索引（Index）”的模式。为 Agent 在主项目中划定一个专属的、结构化的记忆空间，降低重启对话时的上下文恢复成本。

1. 标准目录结构

在主项目中新建一个隐藏文件夹（如 .agent），专门存放由 Agent 生成和读取的工程管理文档。

📁 Project_XXX/  (你的主项目目录)
├── 📁 src/                              (正式代码)
├── 📁 .agent/                           (👉 Agent 专属工作区)
│   ├── 📄 README.md                     (说明书：定义目录结构与行为规范)
│   ├── 📄 state.md                      (总控面板：全局状态机与进度索引)
│   ├── 📁 01_plans/                     (规划区：任务拆解与架构设计)
│   ├── 📁 02_reports/                   (沉淀区：里程碑总结与实验复盘)
│   └── 📁 03_context/                   (弹药库：API文档、论文片段、技术栈约束)

2. 核心文件定义与维护逻辑

📄 README.md (给 Agent 看的说明书)

• 作用： 定义该文件夹的运转规则，确保无论切换到哪个大模型，它都能迅速理解你的工程管理逻辑。

• 内容模板：

  • 声明各子文件夹（01_plans, 02_reports 等）的具体用途。
  • 强制规定： “每次生成新 Plan 前必须先读 state.md”；“每次完成任务必须在 02_reports 写总结，并同步更新 state.md”。

• Example：

  # Agent Workspace System
  这是本项目的 Agent 专属工作区，用于存储任务规划、进度报告和上下文资料。
  
  ## 目录结构说明
  - **01_plans/**: 存放任务拆解和执行计划。文件名格式：`stepN_描述.md`。
  - **02_reports/**: 存放里程碑总结。当一个 Plan 执行完毕，请在此生成对应的 Report。
  - **03_context/**: 存放静态参考资料（如项目相关的 API 文档、论文摘要、技术规范）。
  - **state.md**: 整个工作区的“状态机”，记录当前进度和最新文件的链接。
  
  ## Agent 操作规范
  1. 每次开始新任务前，请先读取 `state.md` 确认当前进度。
  2. 每一个重要的行动方案必须先在 `01_plans/` 生成计划。
  3. 任务完成后，必须在 `02_reports/` 提交总结，并同步更新 `state.md`。

📄 state.md (总控面板 / 状态机)

• 作用： 整个项目的“游标（Cursor）”。每次开启新对话时，这是唯一需要强制 Agent 首先读取的文件。
• 内容板块：
  • 开头：“System Note: 本项目采用结构化管理。详细目录规范见 .agent/README.md。当前任务状态如下：”
  • [Current Goal]: 当前正在攻克的具体技术问题。
  • [Context Links]: 指向当前正在执行的最新计划文件路径（例如 见 01_plans/step3_optimization.md）。
  • [Done]: 简述已完成的里程碑，避免 Agent 重复造轮子。

📁 文件夹命名与使用规范

• 01_plans： 按模块或执行顺序命名（如 01_midi_parsing_plan.md）。指导未来行动。
• 02_reports： 记录跑通的实验、跑崩的教训或阶段性成果（如 report_inference_latency.md）。沉淀历史经验。
• 03_context： 存放静态参考资料。Agent 在写代码或出方案前，可直接读取此处的文档以对其技术栈。

3. 最佳实践 SOP（标准操作流程）

步骤一：项目初始化（注入记忆）

在开启一个全新对话框时，使用以下 Prompt 进行引导：

“在这个项目中，我为你准备了一个专属的记忆空间 .agent/。请你先阅读 .agent/README.md 了解你的文件管理规范，然后读取 .agent/state.md，告诉我当前进度，我们接着干。”

步骤二：执行与迭代（自动化维护）

在要求 Agent 编写代码或输出长篇报告时，在 Prompt 尾部加上维护指令：

“请根据刚才的讨论在 01_plans/ 生成一份新的架构规划。完成后，务必同步更新 state.md 中的 [Current Goal] 和 [Context Links]，以反映最新的项目状态。”

步骤三：中断与恢复（无缝衔接）

过了半个月再回到该项目时，不需要拼凑历史聊天记录，直接开新对话让 Agent 读取 state.md 即可瞬间恢复全盘上下文。