文档驱动的AI协作 (DDAC) 工作流

这份文档是您与Gemini进行高效、标准化项目开发的行动指南。

---

产物一：标准化的首次提示词模板

每次开启一个新项目时，请完整复制下方的模板，仅修改 `[---项目需求描述---]` 部分，然后将其作为我们对话的开场白。

# Gemini AI 协作项目启动指令## 1. 协作身份与目标你好，Gemini。在此次对话及后续的项目开发中，你的角色是我的AI架构师与核心开发伙伴。我们的共同目标是遵循“文档驱动的AI协作 (DDAC)”工作流，高效地构建一个高质量、文档完善的软件项目。## 2. 我们的工作流程协议 (DDAC)我们将严格遵循以下工作流程：* **单一事实来源**: Sphinx生成的文档是我们之间沟通的唯一事实来源。
* **文档先行**: 所有开发任务都始于创建或更新文档（特别是代码中的docstrings）。
* **自动化**: 我们会利用Sphinx的autodoc功能，确保代码变更能实时、自动地反映在项目文档中。
* **上下文清晰**: 在执行具体任务时，我们会通过引用已有的文档页面或编写完整的docstring来提供清晰、无歧义的上下文。## 3. [---项目需求描述---]**(请在这里详细填写你的项目需求，越具体越好。以下子标题可作为参考)**### 3.1 项目愿景与核心价值
* **一句话描述**: (例如：一个帮助用户追踪个人读书进度的Web应用。)
* **目标用户**: (例如：热爱阅读、希望量化自己阅读习惯的学生和职场人士。)
* **要解决的核心问题**: (例如：用户常常忘记读了哪些书、读到哪里，无法形成阅读闭环。)### 3.2 核心功能模块 (Features)
* **用户模块**: (例如：用户注册、登录、个人信息管理。)
* **书籍模块**: (例如：通过ISBN或书名搜索并添加书籍到书架、展示书籍详情。)
* **进度追踪模块**: (例如：记录每本书的阅读页数或百分比、添加读书笔记、展示阅读统计图表。)
* **(其他模块...)**### 3.3 技术与环境约束 (Constraints)
* **主要语言**: (例如：Python)
* **部署环境**: (例如：Docker容器，部署在云服务器上。)
* **性能要求**: (例如：所有API请求的响应时间应在200ms以内。)
* **依赖偏好/限制**: (例如：后端框架倾向于使用FastAPI；数据库使用PostgreSQL。)## 4. 你的任务 (Your Tasks)基于以上信息，请执行以下任务：1.  **技术选型与架构建议**:* 推荐一个完整的、现代化的技术栈 (具体到框架、数据库、关键库的版本)。* 设计一个清晰的项目顶层架构 (例如：分层架构、微服务，并说明理由)。2.  **项目文件结构设计**:* 给出一个详细的目录和文件结构树，并对核心文件/目录的职责进行简要说明。3.  **生成“创世文档”**:* 为我们即将创建的Sphinx项目，生成以下三个核心文档的reStructuredText (`.rst`) 格式的原始内容。内容必须专业、详尽，并与你前面推荐的技术和架构保持一致。* `project_goals.rst`: 详细阐述项目目标、用户画像和核心功能。* `architecture.rst`: 详细说明你推荐的技术栈、系统架构图（可以使用`.. graphviz::`占位）和关键设计决策。* `coding_style.rst`: 提供一套基于PEP 8的、针对此项目的具体编码规范和API设计指南。

产物二：“文档驱动的AI协作”工作流手册

请将此手册作为您在项目开发全过程中的行动指南。

阶段 0：项目启动 (Project Ignition)

1. 准备提示词: 复制上方的“标准化的首次提示词模板”。
2. 填写需求: 仔细填写模板中的 `[---项目需求描述---]` 部分。
3. 启动对话: 将填写好的完整提示词发送给Gemini。
4. 评审与确认: 与Gemini讨论技术选型、架构和文件结构，直到达成共识。
5. 生成创世文档: Gemini会根据最终方案，生成 `.rst` 文件的内容。
6. 初始化项目:
   • 根据提供的文件结构，在本地创建项目目录。
   • 在项目根目录下，运行 `sphinx-quickstart` 创建 `docs` 目录。
   • 将生成的 `.rst` 内容粘贴到 `docs/source/` 目录下的对应文件中。
   • 配置 `docs/source/conf.py` (启用 `autodoc` 等扩展)。
   • 在 `docs` 目录下运行 make html，生成第一版项目文档。
   • 至此，项目的“宪法”已经建立。

阶段 1：功能开发循环 (Feature Development Cycle)

这是最高频的日常工作流程。

1. 开启新任务: 在PyCharm的Gemini聊天窗口 清理对话 或开启新会话，确保上下文干净。
2. 任务简报:

   指令示例: “我们现在开始开发用户注册功能。请参考 project_goals.rst 中的相关描述。”

3. 定义“代码合约” (Docstring First):

   在你计划添加新函数/类的 `.py` 文件中，首先编写一个完整的、符合Sphinx规范的docstring。

4. 委托AI实现: 在docstring下方的代码区或聊天窗口中，明确指示AI根据该docstring进行开发。

   指令示例: “@gemini: 请根据上面的docstring实现此函数。”

5. 评审与迭代: 审查AI生成的代码是否完全符合docstring的“合约”要求。
6. 构建并验证文档:
   • 在终端运行 make html。
   • 打开浏览器刷新本地文档，亲眼确认新功能及其文档已正确显示。这是闭环的关键一步。

阶段 2：重构与维护 (Refactoring & Maintenance)

1. 锁定目标: 清理对话，明确指出要重构的模块或功能。
2. 引用权威文档:

   指令示例: “我们需要重构用户密码更新的逻辑。当前实现请参考文档 docs/build/html/users/services.html#update_password。新的需求是必须增加旧密码校验环节。”

3. 先改“合约”: 首先修改相关函数的docstring，以反映新的业务逻辑。
4. 委托AI重构:

   指令示例: “`update_password` 函数的docstring已更新。@gemini: 请重构此函数的代码，使其与新的docstring保持一致。”

5. 构建并验证: 再次运行 make html，确保文档和代码同步更新。