Skill: doc-todo-log-loop

1. 概述 (Overview)

本 Skill 定义了一种人机协作的开发工作流，其核心是文档驱动、日志记录的迭代循环。它旨在通过清晰的步骤和产出物，确保开发过程的规范性、可追溯性和高质量，同时允许用户自由控制开发节奏。

此工作流特别适用于需要设计、过程记录和阶段性确认的软件功能开发或问题修复任务。

2. 核心工作循环 (Core Workflow Loop)

本工作流由用户（项目负责人）和 Gemini（开发助理）交替执行，遵循以下核心步骤：

步骤 1: 背景描述 -> 文档撰写 (User -> Gemini)

• 触发: 用户提出一个高阶的功能目标或问题背景。
• Gemini 的行动:
  1. 与用户充分沟通，理解背景、目标、约束。
  2. 撰写一份正式的需求描述文档。
  3. 文档应遵循项目章程定义的命名约定。如无特别约定，使用 YYYY-MM-DD-HH-mm-需求-{简述}.md。
  4. 如果 agent 有 plan mode 中已经被接受 of plan 文件，也要留在文档目录下，用文件的创建时间作为文件名上的时间。
  5. 测试预研: 在此阶段应考虑测试策略，并在 tests/ 目录下准备或更新对应的测试用例集（Test Suite）。

步骤 2: 需求描述 -> TODO 拆分 (User -> Gemini)

• 触发: 用户基于设计文档，或直接提出具体的功能需求。
• Gemini 的行动:
  1. 将高阶需求拆解为一系列具体的、可执行的待办事项。
  2. 将这些待办事项结构化地更新到项目章程定义的 TODO.md 文件中。如无特别约定，放在项目根目录下。
  3. 测试关联: 在 TODO 事项中，应明确关联到 tests/ 目录中相应的测试用例。
  4. 每个待办事项应尽可能清晰、原子化。

步骤 3: 任务指派 (User -> Gemini)

• 触发: 用户从 TODO.md 中选择一个或一组待办事项，并明确指示 Gemini 开始执行。
• Gemini 的行动:
  1. 确认任务指令。
  2. 绝不能在收到用户明确指令前，提前进行开发。

步骤 4: 开发与确认 (Gemini -> User)

• 触发: Gemini 接收到开发指令。
• Gemini 的行动:
  1. 执行具体的开发任务，如修改代码、创建文件、安装依赖等。
  2. 验证执行: 在每完成一个原子操作或功能点后，Gemini 应执行关联的测试用例集版本（见第 4 节）。
  3. 结果报告: 向用户请求确认时，必须汇报测试结果（通过/失败/待观察）。
  4. 用户作为审查者和测试者，对 Gemini 的操作结果进行最终确认。

步骤 5: 开发日志记录 (Gemini -> User)

• 触发: 在一个阶段性功能或一个完整的 TODO 事项 经用户确认 完成后。
• Gemini 的行动:
  1. 撰写一份新的开发日志。
  2. 开发日志应遵循项目章程中提及的命名和目录约定。如无特别约定，放在项目日志目录下并在命名中统一命名 YYYY-MM-DD-HH-mm-开发日志-{标题}.md 。
  3. 日志内容应总结本次开发的工作，包括：
     • 实现了哪些功能点。
     • 对代码或项目结构做了哪些主要修改。
     • 遇到了哪些问题，以及是如何修正的（包括用户和 Gemini 双方）。
     • 对后续步骤的建议或说明。
  4. 如果经过了测试，日志也应包含 「验证结果」 部分：
     • 列出执行了哪些测试用例。
     • 列出对应的测试用例集版本（时间戳目录）。
     • 确认功能点已通过验证。
  5. 记录遇到的问题及修正方案。

步骤 6: 版本控制 (User)

• 触发: Gemini 完成开发日志的撰写。
• 用户的行动:
  1. 审查最终的代码变更、开发日志以及测试用例的更新。
  2. 执行 git add 和 git commit 等操作，将本次开发的产出物提交到版本控制系统中。Gemini 不负责此步骤。

3. Gemini 的主动性与约束 (Constraints & Proactivity)

为了提升协作效率，Gemini 在此 Skill 中被赋予了有限的主动性。

• 可以主动:
  • 在完成一个步骤（如步骤 4 或 5）后，主动查阅 TODO.md 和最新的开发日志。
  • 基于查阅结果，向用户 建议 下一步可以执行的任务。例如：“开发日志已记录完毕。根据 TODO.md，下一个待办事项...。需要现在开始吗？”
  • 在步骤 1 中建议创建测试用例。
  • 在步骤 4 中主动执行测试并报告结果。
  • 建议更新测试用例集版本。
• 禁止主动:
  • 绝对禁止 在未获得用户明确指令的情况下，提前开始任何待办事项的开发工作。
  • 禁止在测试未通过的情况下声称任务完成。

4. 测试用例管理 (Test Suite Management)

为了确保测试的可追溯性和版本一致性，本 Skill 采用基于目录的测试用例管理方案。

4.1 目录结构

测试用例集中存放在项目章程指定的目录。采用时间戳目录进行版本化：

test_dir/YYYY-MM-DD-HH-mm-testsuite/

目录内部结构示例：

• readme.md: 测试用例集概述、环境要求、运行方法。
• part1-feature-a/: 模块 A 的测试文件夹。
  • case1-logic-x.md: 具体测试用例 1。
  • case2-ui-y.md: 具体测试用例 2。
• part2-feature-b/: 模块 B 的测试文件夹。

4.2 更新策略 (Copy-on-Update)

当需要更新或增加测试用例时：

1. 全量复制: 用 shell 命令将当前最新的测试用例集目录（如 tests/2026-05-01-10-00-testsuite/）完整复制到一个新的时间戳目录并标记为 editing（如 tests/2026-05-03-09-00-testsuite-EDITING/）。
2. 增量修改: 在新目录下进行修改、删除或新增操作，直到用户确认修改完成。
3. 将目录重命名，去掉 EDITING。
4. 引用更新: 在后续的 TODO.md 和 开发日志 中引用这个新的目录版本。

4.3 测试用例内容规范

每个测试用例文档（.md）应包含：

• ID & 标题: 唯一标识。
• 前置条件: 执行测试所需的初始状态。
• 输入/操作: 具体的执行步骤或数据。
• 预期结果: 明确的成功指标。
• 实际结果: (可选，可在日志中引用) 本次运行的观察。

此约束旨在确保用户对开发节奏有控制权，过程透明可追溯，质量可控。

5. 文档命名与分类规范 (Document Naming & Classification)

本 Skill 默认实施统一的文档命名格式：

YYYY-MM-DD-HH-mm-{类别}-{标题}.md

文档类别定义：

如果用户要求，Gemini 可以随时写文档。命名时，按建议的下列分类进行归类：

1. 开发日志 (最重要): 对过去一段时间开发过程、决策、遇到的问题及解决方式的忠实记录。
2. 需求 (最重要): 忠实记录用户想要实现的功能或达到的目标。仅包含「需求」本身，不含实现细节。
3. 设计: 对即将实施的任务进行的提前分析。可使用包括 系统设计、架构设计、交互设计、需求设计 的子类别。
4. 规范: 定义未来广泛适用的规则、流程或标准。可使用包括 架构规范、代码规范、流程规范 的子类别。
5. 文档: 对已完成的技术实体（如接口、模块、工具）的使用说明和描述。可用 接口文档、模块文档 等子类别。
6. 调研: 对外部技术、互联网资料或其他现有文档的研究与对比分析。
7. 参考: 从外部摘录的资料、API 说明书或原始规范。与「调研」的区别在于其侧重于原样引用而非主动分析。