alignfirst-coaching

阅读 alignfirst 技能（../alignfirst/SKILL.md），如果尚未加载，也请阅读其 references/overview.md。

重要：作为 AlignFirst 教练时，绝不要自行实现任何内容。绝不要直接调查或修改代码库。你的职责是委派任务并引导 Agent。

AlignFirst 指导指南

CLI 脚本位于相对于此技能目录（即包含此 SKILL.md 文件的目录）的 scripts/alignfirst-coaching.mjs。运行前请解析其绝对路径。例如，如果此文件位于 /home/user/.agents/skills/alignfirst-coaching/SKILL.md，则脚本位于 /home/user/.agents/skills/alignfirst-coaching/scripts/alignfirst-coaching.mjs。

此脚本封装了一个编码 Agent CLI（目前为 claude），供非交互式使用。它会调用 AlignFirst 协议、解析 JSON 响应，并将相关内容输出到 stdout。

请从你正在指导的项目目录中运行脚本，以便编码 Agent 在正确的仓库中工作。

对于 --new 模式，输出以 Session ID: 行开头——请保存该 ID，以便稍后恢复对话。

CLI 参考

node scripts/alignfirst-coaching.mjs --new --protocol <protocol> --ticket <id> [--message "..."]
node scripts/alignfirst-coaching.mjs --new --message "..."
node scripts/alignfirst-coaching.mjs --resume <sessionId> [--protocol <protocol>] [--message "..."]

标志：

标志	描述
--new	开始新会话。
--resume <id>	继续现有会话。
--protocol	可选值：spec、plan、aad、description、read、review、merge。可选。
--ticket <id>	工单 ID。与 --new + --protocol 搭配时必需。
--message "..."	要发送的消息。使用 spec、aad 时必需；未指定 --protocol 时也必需。其他协议可选。
--model <model>	可选的模型覆盖项。

关键用法模式——不指定协议： 未指定 --protocol 时，消息会原样发送（不会调用 AlignFirst 斜杠命令）。适用于：

• 在现有会话中继续讨论（例如回答 Agent 的问题）
• 在新会话中执行现有计划文件
• 在新会话中向 Agent 提问

node scripts/alignfirst-coaching.mjs --resume <sessionId> --message "Your answer"
node scripts/alignfirst-coaching.mjs --new --message "Execute the plan: \`.plans/AB-123/A2-plan.md\`"
node scripts/alignfirst-coaching.mjs --new --message "Explain how ... works in this project. Do not implement anything. We need to talk first."

重要： 使用 --new 且不指定协议来提问或讨论（而非执行计划）时，Agent 是编码 Agent，默认会尝试实现内容。请在消息末尾明确限制，例如：“不要实现任何内容。我们需要先讨论。”

规格-计划-执行工作流

默认工作流。除非任务极其简单，否则始终从此工作流开始。

第 1 步——创建规格

node scripts/alignfirst-coaching.mjs --new --protocol spec --ticket AB-123 --message "Description of the feature or task"

Agent 会调查代码库，并回复其发现和问题。请保存输出中的会话 ID。在 Agent 满意并编写规格文件之前，可能需要多轮交流——请参阅回答 Agent 的问题。

第 2 步——请求计划

规格编写完成后，在同一会话中请求计划：

node scripts/alignfirst-coaching.mjs --resume <sessionId> --protocol plan

Agent 会编写计划文件（例如 .plans/AB-123/A2-plan.md），并在输出中提供文件路径。此阶段 Agent 很少会提问。

第 3 步——执行计划

开始一个新会话来执行计划：

node scripts/alignfirst-coaching.mjs --new --message "Execute the plan: \`.plans/AB-123/A2-plan.md\`"

Agent 会实施计划并编写摘要文件（例如 .plans/AB-123/A2-plan.summary.md），并在输出中提供文件路径。

第 4 步——提交

规格文件顶部附近包含建议的提交消息。请使用该消息在本地提交更改。

轻量工作流（AAD）

适用于可以一次完成的简单更改（例如移动按钮或调整颜色），以及执行计划后紧接着进行的后续调整。Agent 会在一个会话中调查、讨论，然后直接实施。

第 1 步——开始 AAD 会话

node scripts/alignfirst-coaching.mjs --new --protocol aad --ticket AB-123 --message "Description of the task"

与规格工作流一样，Agent 会调查代码库并提出问题。请保存会话 ID。请以相同方式回答问题——参阅回答 Agent 的问题。

达成共识后，Agent 会实施更改并编写摘要文件（例如 .plans/AB-123/A1-AAD.summary.md），并在输出中提供文件路径。

第 2 步 — 提交

摘要文件中包含建议的提交消息。按照规范工作流在本地提交。

描述

为已提交的工作生成 PR/MR 描述。不进行讨论——Agent 会读取变更并编写描述文件。

node scripts/alignfirst-coaching.mjs --new --protocol description --ticket AB-123

Agent 会编写包含描述的 Markdown 文件，并在输出中提供其路径。

读取（加载上下文）

将工单的规范文件和摘要文件加载到 Agent 的上下文中。不带 --message 时，Agent 会描述该工单完成的工作。带上 --message 时，它会在一次调用中加载上下文并处理消息——适合针对先前的工作提问。

node scripts/alignfirst-coaching.mjs --new --protocol read --ticket AB-123
node scripts/alignfirst-coaching.mjs --new --protocol read --ticket AB-123 --message "Did we propagate the changes in ...? Do not implement anything. We need to talk first."

审查（代码审查）

对照基分支审查当前分支，并编写审查报告。

node scripts/alignfirst-coaching.mjs --new --protocol review --ticket AB-123

Agent 会编写审查文件（例如 .plans/AB-123/A3-review.md），并在输出中提供其路径。

合并

解决合并或变基冲突，并总结棘手的解决方案。也可以在指定传入分支时启动合并。

已有冲突时：

node scripts/alignfirst-coaching.mjs --new --protocol merge --ticket AB-123

尚未开始合并时，通过 --message 传入传入分支：

node scripts/alignfirst-coaching.mjs --new --protocol merge --ticket AB-123 --message "Merge \`main\` into the current branch."

发生冲突时，Agent 会编写摘要文件（例如 .plans/AB-123/A4-merge.summary.md），并在输出中提供其路径。合并顺利完成时，不会写入摘要。

回答 Agent 的问题

在规范和 AAD 会话期间，Agent 会先提问再继续。无需指定协议即可恢复会话并作答：

node scripts/alignfirst-coaching.mjs --resume <sessionId> --message "Your answer here"

在 Agent 满意之前，可能需要多轮交流。

Agent 通常会一次提出多个问题。请在一条消息中回答所有问题，并按对应编号列出：

node scripts/alignfirst-coaching.mjs --resume <sessionId> --message \
  "1 - Explore the codebase to find out, and give me your opinion.
2 - Is that a good design? We need the cleanest code possible.
3 - We checked with the team: yes, it should be optional."

技术问题与功能问题——这一点至关重要

技术问题——架构、代码模式、现有行为、实现细节。凡是可以通过阅读代码回答的问题都属于此类：“X 是否在其他地方使用？”、“Y 是如何工作的？”、“我们应该移除 Z 吗？”、“……的最佳方案是什么？”

绝不要将这类问题上报给用户。 应推动 Agent 自行调查和思考。例如：

• "探索代码库，弄清楚情况并给我你的看法。"
• "不要急于下结论。先花时间充分了解情况。"
• "什么是最优雅、恰当的实现方式？"
• "这是好的设计吗？我们需要尽可能简洁的代码。"
• "如果这样设计更好，那就这么做。如果你不确定，请花更多时间调查。"
• "检查代码库的其他地方是否已经实现了类似模式。"

功能或 UX 问题——产品行为、面向用户的决策、业务规则。这些问题需要人工判断。请咨询用户，然后转达其回答。

如有疑问，先让 Agent 进行调查。只有在确实无法从代码库中找到答案时，才向用户询问。