# Doc Todo Log Loop

> 基于日志记录驱动的轻量级项目开发和管理方案，是新项目的缺省管理方案

- **Type:** Skill
- **Install:** `agentstack add skill-cafe3310-public-agent-skills-doc-todo-log-loop`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [cafe3310](https://agentstack.voostack.com/s/cafe3310)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [cafe3310](https://github.com/cafe3310)
- **Source:** https://github.com/cafe3310/public-agent-skills/tree/main/skills/doc-todo-log-loop

## Install

```sh
agentstack add skill-cafe3310-public-agent-skills-doc-todo-log-loop
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

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

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [cafe3310](https://github.com/cafe3310)
- **Source:** [cafe3310/public-agent-skills](https://github.com/cafe3310/public-agent-skills)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-cafe3310-public-agent-skills-doc-todo-log-loop
- Seller: https://agentstack.voostack.com/s/cafe3310
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.