doc-todo-log-loop

name	doc-todo-log-loop
description	基于日志记录驱动的轻量级项目开发和管理方案，是新项目的缺省管理方案
license	Apache-2.0
author	github/cafe3310
depends_on_skill	[]
depends_on_binary	[]

Skill: doc-todo-log-loop

1. 概述

文档驱动、日志记录的人机协作开发工作流。用户控制开发节奏，Agent 负责文档撰写、任务拆分、开发执行和日志记录。

2. 概念定义

以下为默认路径和命名约定。项目章程有特别约定时，以项目章程为准。

• 文档目录: 默认为项目根目录下 backlog/，存放需求、设计、日志等文档
• TODO 文件: 默认项目根目录下 TODO.md
• 测试目录: 默认项目根目录下 tests/
• 文档命名: YYYY-MM-DD-HH-mm-{类别}-{标题}.md
• 测试用例集命名: tests/{YYYY-MM-DD-HH-mm}-testsuite/
• 测试用例命名: part{序号}-{模块}/case{序号}-{简述}.md，在测试用例集内部

3. 文档类别和编写风格

除了后面的工作流之外，若用户要求，Agent 可以随时写文档。 文档命名中的 {类别} 按以下分类取值：

• 开发日志: 开发过程、决策、问题及解决方式的记录。
• 需求: 用户想要实现的功能或目标。仅含需求本身，不含实现细节。
• 设计: 对即将实施任务的提前分析。子类别：系统设计、架构设计、交互设计、需求设计。
• 规范: 定义广泛适用的规则、流程或标准。子类别：架构规范、代码规范、流程规范。
• 说明: 对已完成技术实体的使用说明。子类别：接口说明、模块说明。
• 调研: 对外部技术或资料的研究与对比分析。广泛搜索，记录来源，写出细节而非过度摘要。
• 参考: 从外部摘录的原始资料。与调研的区别在于侧重原样引用而非主动分析。

文档的主要读者是未来的 Agent 和开发者。所有文档、过程日志与说明均保持精简、克制、平和、去形容词、去比喻化。无需冗长描述。记录人类决策、问题和修正方案。提供检索和理解所需的最小说明即可。

当用户指示或流程需要进行互联网调研时：广泛搜索相关资料；每找到一份资料，即记录为一份独立的调研文档，按命名约定命名；文档要记录来源，写出方案、观点、方法的细节，不要过度摘要。

4. 主要工作循环

本 Skill 定义的主要工作流由用户和 Agent 交替执行，遵循以下步骤：

步骤 1: 背景描述 → 文档撰写

• 触发: 用户提出功能目标或问题背景。
• Agent 行动:
  1. 与用户沟通，理解背景、目标、约束。
  2. 撰写需求描述文档（命名：YYYY-MM-DD-HH-mm-需求-{简述}.md）。
  3. 如有 Plan Mode 中已接受的 Plan 文件，移动到文档目录并合理命名。
  4. 如项目含测试，在 tests/ 下准备对应的测试用例集（结构见「测试用例管理」一节）。

步骤 2: 需求描述 → TODO 拆分

• 触发: 用户基于文档或直接提出具体需求。
• Agent 行动:
  1. 将需求拆解为具体、原子化的待办事项，更新到 TODO.md。
  2. 每个事项关联 tests/ 中对应的测试用例。

步骤 3: 任务指派

• 触发: 用户从 TODO.md 中选择事项并明确指示执行。
• Agent 行动: 确认指令，了解必要文档，了解测试诉求，然后进入开发和验证。

步骤 4: 开发与验证

• 触发: 用户下达开发指令。
• Agent 行动:
  1. 执行开发任务。
  2. 每完成一个功能点，按关联的测试用例逐项验证（测试用例为人工检查清单，Agent 按步骤操作并记录结果）。
  3. 向用户报告时必须包含验证结果（通过/失败/待观察）。
  4. 用户进行最终确认。
• 约束: 验证未通过时，禁止声称任务完成。

步骤 5: 开发日志记录

• 触发: TODO 事项经用户确认完成后。
• Agent 行动:
  1. 撰写开发日志（命名：YYYY-MM-DD-HH-mm-开发日志-{标题}.md），内容包括：
     • 实现了哪些功能点
     • 对代码或项目结构的主要修改
     • 遇到的问题及修正方式(包括用户和 Agent)
     • 后续步骤建议
  2. 如经过测试，日志中包含验证结果：执行了哪些用例、对应的用例集版本、验证结论。
  3. 日志完成后，可查阅 TODO.md 并向用户建议下一步任务，但不主动开始。

步骤 6: 版本控制

• 触发: 开发日志撰写完成。
• 用户行动: 审查变更，并执行 git 提交。Agent 不负责此步骤。

5. 测试用例管理

测试用例为 Markdown 格式的人工检查清单，存放在 tests/ 目录下，以时间戳目录进行版本化：

tests/YYYY-MM-DD-HH-mm-testsuite/
├── readme.md                         # 概述、环境要求、执行方法
├── part1-{模块名}/
│   ├── case1-{简述}.md
│   └── case2-{简述}.md
└── part2-{模块名}/

每个测试用例文档包含：

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

首次创建

在步骤 1 中直接创建新的时间戳目录，编写测试用例。

版本更新

1. 将当前最新的测试用例集目录完整复制到新的时间戳目录，加 -EDITING 后缀。
2. 在新目录下增删改，直到用户确认。
3. 去掉 -EDITING 后缀。
4. 在 TODO.md 和开发日志中引用新版本。