优化你的项目开发流程

---

以下经验来源于油管博主：Avthar

https://www.youtube.com/watch?v=aQvpqlSiUIQ

本博客旨在吸收经验，基于此总结出一套可以实地落地的开发方案，看完你也可以按照我的步骤进行项目初期的部署~~

他总结出项目开发的具体流程总结为PSB：Plan、Setup and Build

阶段一（Plan）

这个阶段的核心是在编写任何代码之前，为项目设定好清晰的成功路径

实现细节

1. 进行头脑风暴 ： 通过文档记录（如docs/discovery/brainstorm.md）你想通过项目实现的具体内容

Tips：在项目开始前，总要问自己两个问题：

• “你到底想做什么？或者你的项目目标是什么？” （明确自己真正想要什么，会彻底改变你处理项目的方式，这决定了你需要重点构建什么以及可以省略什么）

• “你想要实现的功能里程碑是什么？” （将项目分解为清晰的阶段，如先确立最小可行性产品 MVP 以及后续的改进版本，如增加框架，润色优化）

2. AI完善ProjectPlan

   向 Claude 或 ChatGPT 描述你的想法，让 AI 帮你梳理思路，并总结成 Markdown 文件（因为你那时的想法还很模糊，甚至很难写出来，用语言输入大声说出来能更容易理清你的思路）

3. 创建项目规格文档 (​​docs/project_spec.md​​ )

   这里建议放到docs/​根目录下，它要求Agent所有逻辑推导必须以此为最高准则，也利于多Agent并行协作。

   

   文档中包含两个关键部分，包含有：

   • PRD产品需求文档（三个关键问题：目标用户是谁、解决什么问题、产品该做什么）

     

     有时候你需要思考目标用户是什么，想为他们解决什么样的问题，有时候那个目标用户是你自己。所以，要花些时间想想，提出具体的描述，避免Claude去提出假设，做出不尽人意的产品。

     你对用户体验的流程描述的越具体，Claude就能越好的帮你实现

   • EDD工程需求文档（技术栈选择、系统设计、数据库模式、API 设计等）

重要提示

• ​需求必须具体：具体描述用户体验和交互细节（例如：工作流是怎样的？能否加照片？），避免 Claude 自行假设。
• 让 AI 向你提问：将头脑风暴内容(brainstorm.md​)发给 AI，让它反问你可能没有想到的边界问题，这能帮你发现未考虑周全的盲点。
• 明确你的技术栈：如果不明确说明，Claude 可能会随机注入你不需要的技术
• 不要试图一次性构建所有内容：先构建版本一 (MVP)，然后根据反馈迭代，为每个里程碑定义完成的标准，以便Claude明确目标。

阶段二（Set up）

• 设置 GitHub 仓库

  通常在Claud.md要求Claude为他开发的每个项目创建一个新的分支，完成后将分支merge或向主分支发起PR。

  **分支：** 
  - 在开始重大更改之前始终创建功能分支
  - 切勿直接提交在主分支 'master' 
  - 分支命名：'feature/description' 或者 'fix/description' 
  

  多利用Issue

• 设置 claude.md 文件

  作为项目的“记忆”，包含项目目标、架构概述、设计规范、安全约束和仓库礼仪等。

  它的内容不宜过多，要确保重点放在最重要的信息上，避免变得臃肿，Claude会

  ​/init

• 创建环境变量文件 (.env)

  让 Claude 生成模板(.env.example)后并填入 API 密钥，避免它在编码时停下来向你索要

  prompt：请基于当前项目规范和技术栈创建一个示例ENV文件，根据创建的模板来填写所需的凭据和API密钥，接下来使用相关技术栈的配置则从这里获取

• 维护Memory

  定期更新项目的上下文信息，每隔一个重要节点让Claude及时更新这些文档，这样会话中始终掌握最新的上下文信息。

  prompt：update memory in ./claude.md

• 配置三个核心文件

  1. ​docs/architecture.md：结构文档记录你的系统设计，应用程序结构以及主要组件的交互方式，并保持功能更新

  2. ​docs/changelog.md：变更日志用于记录项目随时间推移而发生变化

  3. ​docs/project_status.md：项目状态文档，主要维护三个维度：

     • 项目的里程碑有哪些？
     • 在这些里程碑里你完成了哪些工作？
     • 你上次完成了什么？你接下来要做的是什么？

     

• 设置 MCP服务器 和 必要插件

  连接外部工具，如数据库、Playwright（用于前端测试）和 Vercel。

• 设置子代理 (subagents)

  用于自动化特定任务，如生成变更日志、前端测试和复盘优化。

  这里推荐设置三个子agent：

  • 变更日志：在完成一项功能后，创建和更新变更日志changelog.md
  • 前端测试：用于测试前端并能自动运行的脚本测试的代理
  • 回顾代理：在开发会议结束后反思哪些地方可以改进，然后将这些建议更新到Claude.md​或prompt中

• 高级设置（Hooks）

  预先配置权限避免等待授权，并设置 Hooks（如失败重试或 Slack 通知）以实现高级自动化

阶段三：构建 (Build)

开始利用 Claude 编写代码，涵盖从 MVP 到复杂功能的开发

工作流介绍

• 常规工作流 (General workflow) ：建议在开发单一功能时使用，包含四个步骤：研究 -> 计划 -> 实施 -> 测试

  • 在研究与计划环节中，建议将研究报告放到docs/research/目录下。

    将Claude plan mode打开，prompt：

    让我们处理第14个问题，即提升Nano Banana Pro生成缩略图的质量。你的任务是首先撰写一份研究报告，报告放到docs/research/banana_research.md中，阐述如何引导模型生成优质的图像。同时请参考@nano_banana_transcript.txt文件，这是一段关于这一理念的YouTube视频内容。但请结合网络搜索结果来补充你的研究内容，请将研究报告保存在文档文件夹中

  • 在实施和测试过程中，使用官方插件的/feature-dev命令，确保阶段工作流开发不翻车，它包含代码库探索、架构设计和质量审查的专用代理在内的全面功能开发工作流，参考prompt：

    

    /feature-dev 请读取 xxx 文件夹下关于“Nano Banana Pro 缩略图质量提升”的研究报告，根据报告中的优化策略修改

• 基于 Github Issue 工作流 (Issue-based workflow) ：将 GitHub Issues 作为 Bug 和新功能的“事实来源”，让 Claude 直接处理特定的 Issue。

  • 可以自定义命令行或子代理，让它接受文件或文件夹作为输入，并使用github cli输出我的仓库中的github issue，这里我自定义了一个命令行/create-issue，这样每次有需求都可以创建github issue。你可以让Claude自定义一个，这是参考prompt：

    你的任务是为 Claude 添加一个名为 create-issue 的自定义命令模式，要求全局生效 逻辑要求：

    该模式需具备分析用户通过 @引入的文件或文件夹的能力。

    具备能根据用户的要求，理解要求并创建对应Issue的能力。

    它需要调用 gh issue list检索当前仓库的 Issue 以进行去重校验。

    确认无误后，构造 gh issue create 命令。Issue正文需包含：问题描述、受影响的文件路径及改进建议，并输出对应仓库中的github issue。
    请直接修改配置文件并应用更改

    当要创建Issue时，可这样说：

    请分析 @(或你的核心代码目录) 以及之前的研究报告文档。
    针对提升 Nano Banana Pro 缩略图质量的目标，识别出代码中尚未实现的 3 个关键工程点，并为它们分别创建 GitHub Issue。
    标签使用 enhancement，并在正文中引用 docs/research/banana_report.md 中的结论

    当要处理Issue时，可这样说：

    // 快速开发版本：
    处理 Issue #14

    // 先计划后实施：（开启 plan mode）
    针对 Issue #14 制定实施细节

  • 这套工作流的优势是可以将项目里程碑或问题让Claude帮你拆分成若干个Github Issue，而不必在项目上留下大量的文档。

• 多代理工作流 (Multi-agent workflow) ：利用 Git Worktrees技术，在隔离的目录和分支中同时运行多个 Claude Code 实例，从而并行开发多个功能，最后再合并，这是先进的开发流程。

  多代理工作流利用​​claude.md​​文件配置的开发准则与自定义命令行的方式实现。能达到虽然多个会话的​​memory​​进度不同，但由于它们处于同一个 Git 仓库的不同 worktree，​**通过同步​ ​​claude.md​​ ​并在提交时拉取最新文档，可以实现不同 Agent 实例间的知识对齐。**

  先要进行前置配置：

  • ​claude.md三条约束：

    • 在项目完成里程碑或主要新增内容后，更新docs/project_spec.md文件。

    • 在git进行提交时使用 /update-docs-and-commit 命令。

    • 所有的逻辑实现必须溯源至 docs/project_spec.md。若代码实现与规格说明不符，以规格说明为准，若需要修改，则需要询问用户是否要更新文档，再写代码。

  • 自定义命令：

    ​/setup​：内置/init​命令，初始claude.md后自动增加以上三条约束。创建prompt：

    定义 /setup 命令，要求全局生效。
    逻辑：检查 claude.md 是否存在，若无，则执行/init 命令，等待/init 命令成功执行后，再向claude.md 添加三条开发核心准则
    （提示：此时claude.md文件由于执行了/init 命令，所以是肯定会存在的）；
    若已经存在，则在 ##Documentation 章节后追加三条开发核心准则。三条开发核心准则分别为：
    -在项目完成里程碑或主要新增内容后，更新docs/project_spec.md文件。
    -在git进行提交时使用 /update-docs-and-commit 命令。
    -所有的逻辑实现必须溯源至docs/project_spec.md。若代码实现与规格说明不符，以规格说明为准，若需要修改，则需要询问用户是否要更新文档，再写代码。

    另外严格要求： 所有的文件写入操作必须是幂等的（Idempotent），即重复运行 /setup 不会导致内容重复堆叠。

    二改：后续增加了维护文档的需要，升级/setup命令

    升级我之前配置的 /setup 自定义命令行的执行逻辑，使其在执行时除了原有的功能外，另外包含以下自动化行为：

    1.文件模板初始化：在项目根目录自动创建/docs文件夹（如果不存在），并生成以下三个文件的初始结构：

    -docs/architecture.md：包含系统架构图占位、核心组件说明、技术栈清单。

    -docs/changelog.md：包含版本记录表格（日期、变更项、作者、关联Issue）。

    -docs/project_status.md：包含三个固定的 Markdown 标题：## 里程碑、## 已完成工作、## 待办与后续计划

    2.设定更新准则：在 claude.md 中Project Rules中加入以下逻辑：

    -架构对齐：每当引入新的第三方库、修改核心类交互或调整数据库模式时，必须同步更新 docs/architecture.md。
    -变更溯源：每次 Git 提交前，需在 docs/changelog.md 中追加一条简要变更记录。
    -进度锚定：在每个任务（Issue）开始前，先读取docs/project_status.md确认当前里程碑；任务完成后，更新该文件的“上次完成”与“接下来要做”部分

    3.要求：依旧是确保 setup逻辑是幂等（Idempotent）的：如果文件已存在，仅检查缺失的部分并补齐，不要覆盖用户已写的内容

    ​/update-docs-and-commit：这个命令的作用是当git提交的时候会自动更新claude.md文件同时进行一次git提交，确保文档和代码保持同步，也有利于并行agent处理。创建prompt：

    配置自定义命令，要求全局生效：新增 update-docs-and-commit命令，逻辑如下：
    首先，分析自上次提交以来的代码变更及实现的关键里程碑。
    其次，将这些摘要自动追加或更新到 claude.md的“进度记录”或“架构变更”章节中。
    最后，执行 git add . 并根据刚才生成的摘要自动撰写 commit message 运行 git commit

实现流程

Step 1：创建 docs/discoverybrainstorm.md，写下你的所有直觉、痛点和核心功能点。

Step 2：给 Claude 发送指令，根据 Claude 的反馈完善想法，然后让它基于对话结果直接生成 docs/project_spec.md，prompt：

你现在是一名具备严谨学术标准和深厚工程背景的资深架构师。请阅读 @docs/research/brainstorm.md。

任务目标：不要止步于浅层的几个问题。你的目标是通过递归式提问，挖掘我未考虑到的工程风险与产品边界问题。在回答我的问题前，请按以下维度发起询问：

本质意图：明确该项目的终极目标。是技术验证、学习性练习、还是准备投入生产的 MVP？不同的目标决定了后续技术栈的容错率。

里程碑规划：识别功能依赖链。请问如何定义 MVP 的硬性边界？后续的扩展版本中，哪些是“必须有”而哪些是“锦上添花”？

工程规格：

    技术栈选择：是否存在对特定框架或模型的依赖偏好？

    接口设计：系统之间是同步阻塞调用还是异步事件驱动？

产品契约：

    目标用户画像：解决的是开发者的效能问题，还是最终用户的业务痛点？

    核心指标：如何量化该项目的成功？（如响应延迟低于 200ms）。

交互要求：

可以基于问题提出用户建议，或让用户自行描述。

持续向我提问，直至你有95%的信心能够执行项目。

请分批次提出问题，确保逻辑链条严密。

在我完成所有回答后，请将我的回答与头脑风暴内容整合，最终输出为项目规格文档docs/project_spec.md：里面包含PRD（产品需求文档）和 EDD（工程设计文档）部分。

Step 3： 接下来就可以进行你的工作了~~

推荐目录结构

.
├── .claudecode.json
├── claude.md # 项目动态记忆
├── docs/ # 静态规格与研究成果库
│ ├── project_spec.md # PRD + EDD
│ ├── /discovery/brainstorm.md # 存放自己写的头脑风暴 brainstorm.md
│ └── architecture.md # 结构文档记录你的系统设计，应用程序结构以及主要组件的交互方式，并保持功能更新
│ └── changelog.md # 变更日志用于记录项目随时间推移而发生变化
│ └── project_status.md # 维护项目状态文档
├── src/ # 项目源代码
└── pom.xml

重要提示

• 善用plan mode模式

  通过shift + tab开启，让 Claude 思考任务、拆解步骤并提问，然后再开始构建，这样能获得好得多的结果。
  

• 尽可能使用最好的模型

  用Claude去进行规划和复杂任务，开发任务可以交给codex，修bug时则用简单的模型修复，这会大大节省你的时间和token

• 定期维护你的文档

• 不要害怕舍弃

  代码成本很低。如果在原型阶段效果不是很满意的话，大胆撤销甚至直接丢弃该功能重新开始，这能更快找到满意的解决方案~~

希望对你有帮助，祝您身体健康。