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-doneGSD 这套基于 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详见其背后的 工作流实现Framework selection框架选型——主选框架及理由、备选方案、被排除的备选及原因、主动接受的 vendor lock-inImplementation guidance实现指引——来自官方文档的正确语法、核心模式、常见坑杜绝照教程抄但不知所以然Domain context领域上下文——领域专家视角的评分要素Good/Bad/Stakes、该领域特有的失败模式与监管约束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.cjsgsd-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.mdhas_context为 false会提示 Recommended: run /gsd:discuss-phase {N} first to capture framework preferences但仍继续执行——代价是框架选择器将不得不问全所有问题。3.2 幂等处理已有 AI-SPECStep 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 中的特定章节形成清晰的关注点分离步骤子代理负责的 AI-SPEC 章节关键输入5gsd-framework-selectorSection 1系统分类、Section 2框架决策CONTEXT.md、REQUIREMENTS.md7gsd-ai-researcherSections 3/4/4b框架速查、实现指引、AI 最佳实践已初始化的 AI-SPEC、CONTEXT.md8gsd-domain-researcherSection 1b领域上下文AI-SPEC、CONTEXT.md、REQUIREMENTS.md9gsd-eval-plannerSections 5/6/7评测策略、guardrails、生产监控AI-SPEC、CONTEXT.md、REQUIREMENTS.mdStep 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.mdStep 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工具、绝不使用WriteWrite会整体替换文件静默吞掉兄弟代理的成果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 citationMulti-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关注点默认工具Tracing / 可观测性Arize Phoenix——开源、可自托管、经 OpenTelemetry 与框架无关RAG 评测指标RAGAS——faithfulness、answer relevance、context precision/recallPrompt 回归 / CIPromptfoo——CLI-first无需平台账号LangChain/LangGraph 生态LangSmith——若已在该生态则覆盖 PhoenixPhoenix 的接入样例会被写入 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-12Step 10 对生成的 AI-SPEC 做完整性校验逐节确认关键位置非占位Section 2 有真实框架名Section 1b 至少有一条领域 rubric 原料Good/Bad/StakesSection 3 有非空代码块entry point patternSection 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构成由浅入深、可被后续工具机械校验的契约文件章节内容撰写代理1. System Classification系统类型枚举RAG / Multi-Agent / Conversational / Extraction / Autonomous Agent / Content Generation / Code Automation / Hybrid、一段式描述、3-5 条绝不能出错的 critical failure modesframework-selector1b. Domain Context行业垂直、用户群体、风险等级Low/Medium/High/Critical、输出被采纳后的下游后果领域专家评分维度按 Dimension / Good / Bad / Stakes / Source 格式、领域特有失败模式、监管/合规上下文、领域专家角色表domain-researcher2. Framework Decision选定框架 锁定版本 理由、备选框架为何被排除表、Vendor Lock-In 声明Yes/No/Partialframework-selector3. Framework Quick Reference安装命令、核心 imports、最小可运行 entry point、关键抽象概念表、常见坑、推荐项目结构、来源 URLai-researcher4. Implementation Guidance模型配置型号 / temperature / max tokens、核心模式、工具使用、状态管理、上下文窗口策略ai-researcher4b. AI Systems Best Practices跨框架的 AI 工程通识Pydantic 结构化输出、Async-First 设计、Prompt 纪律、上下文窗口管理、成本与延迟预算ai-researcher5. Evaluation Strategy维度表Dimension / Rubric / Measurement / Priority、评测工具链与 CI/CD 集成命令、参考数据集规格规模 ≥ 10、构成、标注方式eval-planner6. GuardrailsOnline实时触发Block/Escalate/Flag与 Offline flywheel采样批次驱动改进闭环两张表eval-planner7. Production MonitoringTracing 工具、3-5 个关键指标、告警阈值、基于信号过滤的智能采样策略eval-planner模板末尾是一份 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 MCPresolve-library-idget-library-docs若因上游 buganthropics/claude-code#13898 会剥离带tools:frontmatter 限制的 agent 的 MCP 工具不可用则回退到 Bash CLInpx --yes ctx7latest 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_phaseboolean默认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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考