/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` 和开发日志中引用新版本。