企业官网建设流程全解析

Get-Shit-Done 的 AI 集成阶段指南：用/gsd:ai-integration-phase在规划前锁定框架、实现方案与评测策略

【免费下载链接】get-shit-doneA light-weight and powerful meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.项目地址: https://gitcode.com/GitHub_Trending/getshi/get-shit-done

在 get-shit-done（GSD） 这套基于 Claude Code 的 meta-prompting 与 spec-driven 开发系统中，当某个 phase（阶段）的产出物是"AI 系统"时，直接进入 planner 编排任务常常会踩中两类最典型的 AI 开发失败模式：为用例选错了框架，以及把评测当作事后补丁。/gsd:ai-integration-phase正是为此设计的一个命令——它在discuss-phase与plan-phase之间生成一份名为AI-SPEC.md 的 AI 设计契约，在规划开始前锁定框架选型、实现指引、领域上下文与评测策略四项关键决策。读完本文，你将理解该命令的完整执行流水线、四个编排子代理的职责切分、AI-SPEC 模板的结构化契约，以及如何在配置中开关该阶段并正确衔接后续的/gsd:plan-phase。

1. AI-SPEC.md：在写任何代码之前先锁定的四件事

AI-SPEC 的设计哲学很直接：AI 系统是非确定性的，单元测试与集成测试不足以证明它在真实场景下行为正确；框架选型与评测方案如果等到编码阶段才决定，返工成本极高。因此 命令定义 的目标是"Create an AI design contract (AI-SPEC.md) for a phase involving AI system development"，并明确指出文件需要locks four things（详见其背后的 工作流实现）：

1. Framework selection（框架选型）——主选框架及理由、备选方案、被排除的备选及原因、主动接受的 vendor lock-in；
2. Implementation guidance（实现指引）——来自官方文档的正确语法、核心模式、常见坑，杜绝"照教程抄但不知所以然"；
3. Domain context（领域上下文）——领域专家视角的评分要素（Good/Bad/Stakes）、该领域特有的失败模式与监管约束；
4. Evaluation strategy（评测策略）——评测维度、具体 rubric、工具链、参考数据集与 guardrail 设计。

这份契约由后续的gsd-planner消费来编排任务、由gsd-eval-auditor消费来做验收（见 AI-SPEC 模板），因此它既是开发前的"设计冻结"，也是开发后的"验收依据"。

在 GSD 的生命周期中，该阶段的位置固定插入在discuss-phase与plan-phase之间：先经过讨论阶段收集框架偏好与用户决策，再由本命令生成 AI-SPEC，最后 planner 依据契约分解任务。

2. 命令的调用形态与生命周期位置

该命令以 Claude Code 斜杠命令形式提供，其 frontmatter 契约定义在 命令文件：

name: gsd:ai-integration-phase description: Generate an AI-SPEC.md design contract for phases that involve building AI systems. argument-hint: "[phase number]" requires: [phase]

• 参数为可选 phase 编号：/gsd:ai-integration-phase 3指定第 3 个 phase；省略参数时自动探测下一个未规划的 phase；
• 前置条件：必须已存在规划（requires: [phase]），若尚未执行/gsd:new-project建立 roadmap，工作流会直接报错提示先运行/gsd:new-project；
• 允许工具集：Read / Write / Bash / Glob / Grep / Agent / WebFetch / WebSearch / AskUserQuestion以及mcp__context7__*（供文档查询 MCP 使用）。

该命令由配置项workflow.ai_integration_phase控制，默认值为true。当设为false时命令会打印 "AI phase is disabled in config. Enable via /gsd:settings." 并退出。相关配置说明见 CONFIGURATION.md 与 planning-config.md，默认值定义在 config.cjs，gsd-sdk query config-get与校验逻辑在 core.cjs 与 verify.cjs 中均有对应实现。

3. 端到端执行流水线：四代理编排全景

命令的整体编排在 工作流文件 中定义，其 objective 可概括为：Framework Select → Research Docs → Research Domain → Design Eval Strategy → Done，共 12 个步骤，中间由四个子代理接力完成（与命令文件 frontmatter 中声明的Orchestrates gsd-framework-selector → gsd-ai-researcher → gsd-domain-researcher → gsd-eval-planner一致）。

3.1 初始化与配置门（Steps 1-3）

工作流首先通过 SDK 初始化阶段上下文并解析模型与配置：

INIT=$(gsd-sdk query init.plan-phase "$PHASE") if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi

从 JSON 中解析phase_dir、phase_number、phase_name、phase_slug、padded_phase、has_context、has_research、commit_docs等字段，并取得state_path、roadmap_path、requirements_path、context_path。随后按子代理逐一解析各自应使用的模型（若未配置则静默降级）：

SELECTOR_MODEL=$(gsd-sdk query resolve-model gsd-framework-selector 2>/dev/null | jq -r '.model' 2>/dev/null || true) RESEARCHER_MODEL=$(gsd-sdk query resolve-model gsd-ai-researcher 2>/dev/null | jq -r '.model' 2>/dev/null || true) DOMAIN_MODEL=$(gsd-sdk query resolve-model gsd-domain-researcher 2>/dev/null | jq -r '.model' 2>/dev/null || true) PLANNER_MODEL=$(gsd-sdk query resolve-model gsd-eval-planner 2>/dev/null | jq -r '.model' 2>/dev/null || true)

接着检查配置门AI_PHASE_ENABLED=$(gsd-sdk query config-get workflow.ai_integration_phase ...)，为false即退出。然后通过gsd-sdk query roadmap.get-phase "${PHASE}"校验 phase 是否存在（found为 false 时报错并列出可用 phase）。前置检查中有一个非阻塞警告：若该 phase 尚无CONTEXT.md（has_context为 false），会提示 "Recommended: run /gsd:discuss-phase {N} first to capture framework preferences"，但仍继续执行——代价是框架选择器将不得不问全所有问题。

3.2 幂等处理已有 AI-SPEC（Step 4）

如果目标 phase 目录下已存在*-AI-SPEC.md，命令不会静默覆盖，而是通过AskUserQuestion让用户三选一：

• Update——以现有文件为基线重新执行；
• View——展示当前 AI-SPEC 内容后退出；
• Skip——保留现状直接退出。

文本模式下（--text参数或配置workflow.text_mode: true），所有AskUserQuestion会替换为纯文本编号列表，由用户键入选项数字——这是面向非 Claude 运行时（如 OpenAI Codex、Gemini CLI）的必需适配，因为那些环境没有AskUserQuestion工具。

3.3 四代理分工：Step 5 到 Step 9

四个子代理按顺序依次被 spawn，各自只负责 AI-SPEC 中的特定章节，形成清晰的关注点分离：

Step 5 —— Spawn gsd-framework-selector。控制台先打印◆ Step 1/4 — Framework Selection...。选择器代理（agent 定义）首先扫描代码库已有技术信号（package.json/pyproject.toml/requirements*.txt，排除node_modules），防止推荐团队已经否决过的框架；随后执行一次不超过 6 问的交互访谈（单次AskUserQuestion调用，涉及系统类型、模型供应商、开发阶段、语言、核心诉求、硬约束），依据 ai-frameworks.md 中的决策矩阵打分：先剔除违反硬约束的框架，再按用户优先级加权评分，产出 Top 3 排名（只展示推荐与理由，不展示评分表）。返回给编排器的结构化结果形如：

FRAMEWORK_RECOMMENDATION: primary: {framework name and version} rationale: {2-3 sentences} alternative: {second choice} system_type: {RAG | Multi-Agent | Conversational | Extraction | Autonomous | Content | Code | Hybrid} model_provider: {OpenAI | Anthropic | Model-agnostic} eval_concerns: {comma-separated primary eval dimensions} hard_constraints: {list} existing_ecosystem: {detected libraries}

选择失败或返回为空时命令直接报错退出，提示重跑/gsd:ai-integration-phase {N}或先到/gsd:discuss-phase {N}回答问题。

Step 6 —— 初始化 AI-SPEC 文件：从模板复制文件并按选择器输出回填头部字段：

cp "$HOME/.claude/get-shit-done/templates/AI-SPEC.md" "${PHASE_DIR}/${PADDED_PHASE}-AI-SPEC.md"

Step 7/8 —— 顺序执行（重要并发约束）。步骤 7 与 8 虽各自写 AI-SPEC 中互不重叠的章节，但必须串行执行——Step 8 必须等待 Step 7 完成后才能 spawn。原因在工作流的 ordering note 中写明，并有对应回归测试 bug-3096-ai-integration-phase-parallel-race.test.cjs 守护：曾出现两个代理被并行调度的真实事故，gsd-domain-researcher收尾时的Write调用会以自己内存中的旧副本整体替换文件，静默覆盖 Step 7 已写入的 Sections 3/4 内容，实际运行中命中率约 40%（5 个 worktree 代理中 2 个触发），恢复成本约额外一次 18 分钟的 ai-researcher 调度。

由此两条工具纪律被固化：

• 两个代理修改共享文件时只能用Edit工具、绝不使用Write（Write会整体替换文件，静默吞掉兄弟代理的成果；Edit只定位目标行）；
• 编辑前必须先核对该章节仍是模板占位符，避免基于过期内容拼写。

测试用例对 Step 7/8 的 prompt 块逐一断言包含Edit tool、NEVER use Write、以及 Step 8 必须包含 wait/complete 指令，防止此回归复发。

Step 9 —— Spawn gsd-eval-planner：打印◆ Step 4/4 — Designing evaluation strategy...，评测规划器（agent 定义）先通读 AI-SPEC（尤其 Section 1b 中领域研究者沉淀的 rubric 原料），再把系统类型映射到 ai-evals.md 中的必需评测维度（如 RAG → context faithfulness/hallucination/answer relevance/retrieval precision/source citation；Multi-Agent → task decomposition/inter-agent handoff/loop detection），用户可见系统永远附加safety、agentic 系统永远附加task completion。随后为每个维度撰写 PASS/FAIL 形式的具体 rubric（以领域语言而非空泛标签），分配测量手段（Code / LLM Judge / Human），标注 Critical/High/Medium 优先级。

3.4 评测工具链的选择逻辑

评测规划器遵循"先探测、后默认"原则：先用 grep 扫描代码库中是否已存在langfuse | langsmith | arize | phoenix | braintrust | promptfoo | ragas等信号，若命中则以其作为 tracing 默认工具；若零命中，则应用一套有主见的默认值（见 eval-planner agent）：

Phoenix 的接入样例会被写入 AI-SPEC 的 Section 7：

# pip install arize-phoenix opentelemetry-sdk import phoenix as px from opentelemetry import trace from opentelemetry.sdk.trace import TracerProvider px.launch_app() # http://localhost:6006 provider = TracerProvider() trace.set_tracer_provider(provider) # Instrument: LlamaIndexInstrumentor().instrument() / LangChainInstrumentor().instrument()

3.5 校验、提交与收尾（Steps 10-12）

Step 10 对生成的 AI-SPEC 做完整性校验，逐节确认关键位置非占位：

• Section 2 有真实框架名；
• Section 1b 至少有一条领域 rubric 原料（Good/Bad/Stakes）；
• Section 3 有非空代码块（entry point pattern）；
• Section 4b 有 Pydantic 示例；
• Section 5 维度表至少一行；
• Section 6 至少一条 guardrail 或显式 "N/A for internal tool" 注记；
• 结尾 checklist 至少勾选 3 项。

校验失败时列出缺失章节，询问用户是重跑对应步骤还是继续。Step 11 在commit_docs为真时以规范化消息提交（如git commit -m "docs({phase_slug}): generate AI-SPEC.md — {primary_framework} + domain context + eval strategy"）。Step 12 打印完成横幅，摘要输出 Framework / System Type / Domain / Eval Dimensions / Tracing Default / Output 路径，并引导下一步：/gsd:plan-phase {N}—— planner 将消费 AI-SPEC.md。

4. AI-SPEC 模板逐节解剖：七段契约 + 检查清单

AI-SPEC 的骨架完整定义在 AI-SPEC.md 模板。它结构化为 7 个编号章节（外加 1b 与 4b 两个补充段）加一份 checklist，构成"由浅入深、可被后续工具机械校验"的契约文件：

模板末尾是一份 16 项的 checklist，例如 "System type classified"、"Critical failure modes identified (≥ 3)"、"Eval tooling selected — Arize Phoenix default confirmed or override noted"、"Reference dataset spec written (size ≥ 10...)"，既是代理自检清单，也是验证步骤的机器可读依据。

5. 四个编排代理的实现纵深

四个代理均为独立 agent 文件，可从 agents 目录查看完整定义：

• gsd-framework-selector.md：回答"What AI/LLM framework is right for this project?"。访谈问题覆盖 8 类系统类型、5 类模型供应商承诺、4 类团队阶段、语言、6 类优先级、7 类硬约束；其成功标准包括"代码库已扫描技术信号""硬约束已用于剔除不兼容框架""返回结构化结果给编排器"。

• gsd-ai-researcher.md：回答"How do I correctly implement this AI system with the chosen framework?"。文档获取走双通道：优先 Context7 MCP（resolve-library-id+get-library-docs），若因上游 bug（anthropics/claude-code#13898 会剥离带tools:frontmatter 限制的 agent 的 MCP 工具）不可用，则回退到 Bash CLInpx --yes ctx7@latest library/docs <name> "<query>"。文档源表覆盖 CrewAI、LlamaIndex、LangChain、LangGraph、OpenAI Agents SDK、Claude Agent SDK、AutoGen/AG2、Google ADK、Haystack 九个主流框架。Section 4b 是它最具跨框架价值的产物——无论选哪个框架都必须写的五小节：Pydantic 结构化输出（含with_structured_output()/instructor/PydanticOutputParser/response_format等框架差异）、Async-First（警惕在事件循环里调用asyncio.run()）、Prompt 纪律（system/user 分离、显式max_tokens）、上下文窗口管理（RAG 重排截断 / 对话摘要 / agent compaction）、成本预算（缓存 + 子任务换廉价模型）。

• gsd-domain-researcher.md：回答"What do domain experts actually care about?"，只研究业务领域、不碰技术框架。它从 phase 产物中提取领域信号（"contract review"→legal、"support ticket"→customer service、"medical intake"→healthcare），执行 2-3 次定向检索，并把评分原料写成双专家能达成一致的 Good/Bad 描述。质量红线明确："Do not fabricate criteria"——只呈现研究或公认的从业者知识；领域确实不清时写最小段落并标注待澄清项。

• gsd-eval-planner.md：回答"How will we know this AI system is working correctly?"。它负责把 Section 1b 的领域 rubric 原料翻译成可测量、有工具落地的评测标准，绝不重复造轮子重推领域上下文。guardrail 取舍遵循 ai-evals.md 的核心判据——"如果该行为出错对我的业务是灾难性的吗？是 → 走在线 guardrail（每条请求实时、必须够快、加延迟所以要保持克制）；否 → 走下线的 flywheel 批次分析"。参考数据集规格要求至少 10 条（生产级 20 条起步），宁要 10-20 条高质量、由领域专家标注，不要 200 条平庸样本。

6. 配置、前置条件与运行提示

运行该命令的完整前提与配置小结：

• 必须已建立规划：对某个 phase 执行前应先有 roadmap（/gsd:new-project//gsd:plan-phase生态内的规划基础设施）；
• 可选启用标记：workflow.ai_integration_phase（boolean，默认true）。禁用时命令以配置门消息退出，需在/gsd:settings中重新开启；health 校验在缺键时给出 W016 警告并可通过--repair自动补默认值；
• 建议先跑/gsd:discuss-phase {N}：虽非硬性阻塞，但能先把框架偏好沉淀进 CONTEXT.md，显著减少框架选择器的交互轮次；
• 文本模式：非 Claude 运行时请使用--text参数或开启workflow.text_mode，让所有交互以编号文本呈现；
• 不要并行修改共享文件：任何人工介入或二次生成都遵循 Step 7/8 沉淀的纪律——对 AI-SPEC 使用Edit而非Write；
• 成功标准（见 工作流文件）：框架选中且理由已记录、AI-SPEC 由模板生成、框架文档与最佳实践已调研（Sections 3/4/4b 已填充）、领域上下文已调研（Section 1b）、评测策略植根于领域上下文（Sections 5-7）、Arize Phoenix（或探测到的既有工具）设为 Section 7 的 tracing 默认、全部关键章节非空校验通过、按需提交、向用户展示下一步。

完整成功示例的最终界面大致如下：

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ GSD ► AI-SPEC COMPLETE — PHASE 3: {name} ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ◆ Framework: {primary_framework} ◆ System Type: {system_type} ◆ Domain: {domain_vertical from Section 1b} ◆ Eval Dimensions: {eval_concerns} ◆ Tracing Default: Arize Phoenix (or detected existing tool) ◆ Output: {ai_spec_path} Next step: /gsd:plan-phase 3 — planner will consume AI-SPEC.md

结语

/gsd:ai-integration-phase的价值在于把 AI 系统开发中最容易拖到后期才暴露的两类问题——错误框架投入与评测缺位——前置到规划阶段用一份结构化的 AI-SPEC 契约强制解决。它通过四个专业子代理的分工协作，将框架决策、官方文档蒸馏、领域专家视角和评测工程四类知识源在一条串行流水线中汇聚成一个既可供 planner 编排任务、又可供 eval-auditor 验收产物的单一事实来源。若你正在用 GSD 规划涉及 RAG、Agent、代码自动化或内容生成的 phase，建议在/gsd:discuss-phase {N}之后、/gsd:plan-phase {N}之前执行本命令，让 AI-SPEC 成为该阶段所有后续任务的设计锚点。

【免费下载链接】get-shit-doneA light-weight and powerful meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.项目地址: https://gitcode.com/GitHub_Trending/getshi/get-shit-done