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 等）均由用户按需显式指示触发。