/guide

name: guide
description: 基于规范驱动与日志记录的轻量级人机协作项目开发与管理方案，包含 /guide load, /guide spec, /guide handoff, /guide test, /guide log 子命令。
license: Apache-2.0
author: github/cafe3310
depends_on_skill: []
depends_on_binary: []

Skill: guide

1. 概述

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

2. 概念定义

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

• `文档目录`: 默认为项目根目录下 `backlog/`，存放需求、设计、日志等文档
• `文档命名`: `YYYY-MM-DD-HH-mm-{类别}-{标题}.md`
• `规范目录`: 默认为项目根目录下 `specs/`，存放项目中长期生效的系统架构、数据契约、开发范式与全局禁忌规范
• `规范命名`: `{编号}-{标题}.md`
• `常用工作流`: 默认为项目根目录下 `workflows/`，存放项目中长期生效的工作流规范
• `常用工作流命名`: `{编号}-{标题}.md`
• `TODO 文件`: 默认项目根目录下 `TODO.md`
• `测试目录`: 默认项目根目录下 `tests/`
• `测试用例集命名`: `tests/{YYYY-MM-DD-HH-mm}-testsuite/`
• `测试用例命名`: `part{序号}-{模块}/case{序号}-{简述}.md`，在测试用例集内部

若无上述目录，可查看这些常见位置：

• `backlog/` 可能在 `docs/`
• `specs/` 可能在 `specifications` 或 `backlog/specs/`
• `workflows/` 可能在 `backlog/workflows/`
• `TODO.md` 可能在 `docs/TODO.md` 或 `backlog/TODO.md`

3. 文档类别和编写风格

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

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

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

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

4. Subcommands

本 Skill 包含以下子命令。这些子命令由人类按需指示触发与加载，Agent 在未收到人类对应子命令指示时无需主动提前加载其具体实现：

• `/guide load`: 探测项目环境，了解工作流和项目规约，加载 `TODO.md`（详见 `references/load.md`）。
• `/guide spec [内容]`: 用来记录长期生效规范，或在用户发现 Agent 忘掉/偏离规范时重新加载并对照应用 Spec（详见 `references/spec.md`）。
• `/guide test [操作]`: 用来记录测试用例清单或触发执行测试验证（详见 `references/test.md`）。
• `/guide log [简述]`: 用于快速收尾：开发日志到 backlog、更新 TODO.md 并提交（Git Commit）所有变更（详见 `references/log.md`）。
• `/guide handoff [焦点]`: 跨 Agent 会话工程开发交接文档生成（详见 `references/handoff.md`）。

5. 主要工作循环

本 Skill 定义的核心开发循环由用户和 Agent 交替执行，遵循以下步骤：

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

• 触发: 用户提出功能目标或问题背景。
• Agent 行动:

1. 与用户沟通，理解背景、目标、约束，并对照已知 Spec 评估架构合规性。 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. 深入阅读任务涉及的相关 Spec，严格对照架构规范执行开发。 2. 每完成一个功能点，按关联的测试用例逐项验证（测试用例为人工检查清单，Agent 按步骤操作并记录结果）。 3. 向用户报告时必须包含验证结果（通过/失败/待观察）。 4. 用户进行最终确认。

• 约束:
• 验证未通过时，禁止声称任务完成。
• 违反已生效 Spec 规范的实现（如数据层违规覆盖、类型越级、破坏分层）视为不合格交付。

其他步骤（如环境与架构加载 `/guide load`、长效规范管理 `/guide spec`、测试触发与管理 `/guide test`、任务收尾与提交 `/guide log`、跨会话交接 `/guide handoff` 等）均由用户按需显式指示触发。