get-shit-done 的 AI-SPEC.md 设计契约模板：在编码前锁定框架、领域与评估策略的落地指南

get-shit-done 的 AI-SPEC.md 设计契约模板：在编码前锁定框架、领域与评估策略的落地指南

【免费下载链接】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

本篇围绕 GSD（get-shit-done）仓库中的 AI-SPEC.md 模板 展开，讲解这份 "AI 设计契约" 的完整结构、每个章节的填写要点，以及它在/gsd:ai-integration-phase工作流中如何被生成、被gsd-planner消费、被gsd-eval-auditor回溯审计。读完本文，你将掌握：如何为任意 AI 系统（RAG、多智能体、对话、抽取、自主 Agent 等）产出一份可规划、可评估、可监控的设计契约，以及仓库源码与测试如何保证这份契约的完整性与一致性。

一、AI-SPEC 是什么：规划开始前的四重锁定

在 GSD 的规范驱动开发（spec-driven development）生命周期中，AI-SPEC.md 是专为"涉及 AI 系统构建"的阶段（phase）设计的设计契约（design contract）。按模板开头的定义，它由/gsd:ai-integration-phase命令生成，被gsd-planner与gsd-eval-auditor消费，其作用是在规划（planning）开始前锁定四件事：

1. 框架选型（Framework selection）—— 含理由与备选方案；
2. 实现指导（Implementation guidance）—— 来自官方文档的正确语法、模式与坑；
3. 领域上下文（Domain context）—— 从业者视角的评估要素、失败模式、监管约束；
4. 评估策略（Evaluation strategy）—— 维度、评分标准（rubric）、工具、参考数据集、护栏。

从仓库的 ai-integration-phase 工作流 可以看到设计意图：该工作流"插入在 GSD 生命周期的 discuss-phase 与 plan-phase 之间"，目的是预防 AI 开发中最常见的两类失败——为用例选错框架，以及把评估当成事后补救。

模板文件头部用引用块明确了契约的生成与消费链路：

AI design contract generated by/gsd:ai-integration-phase. Consumed bygsd-plannerandgsd-eval-auditor. Locks framework selection, implementation guidance, and evaluation strategy before planning begins.

模板以# AI-SPEC — Phase {N}: {phase_name}作为标题占位，{N}为阶段编号、{phase_name}为阶段名称。实际产物文件命名遵循{phase_dir}/{padded_phase}-AI-SPEC.md的规范（见 gsd-eval-auditor 的输入约定）。

二、生成与消费链路：四个 Agent 如何协作

模板不是由人手工填写的白纸，而是由gsd:ai-integration-phase命令编排四个 Agent 分工产出的。命令文档 commands/gsd/ai-integration-phase.md 给出了流水线：Select Framework → Research Docs → Research Domain → Design Eval Strategy → Done，即：

框架选择器（gsd-framework-selector）是流水线的起点：它会先扫描代码库中的package.json、pyproject.toml等技术信号，再进行一次 ≤6 问的面试（系统类型、模型供应商、开发阶段、语言、优先级、硬约束），最后按 ai-frameworks.md 中的决策矩阵打分，输出结构化的FRAMEWORK_RECOMMENDATION（primary / rationale / alternative / system_type / eval_concerns 等字段）供编排器解析。

领域研究员（gsd-domain-researcher）负责回答"领域专家真正关心什么"——研究业务领域而非技术框架，产出 Section 1b，包括 3~5 条"Dimension / Good / Bad / Stakes / Source"格式的评估要素。

AI 研究员（gsd-ai-researcher）负责从框架官方文档提炼实现就绪指导：优先使用 Context7 MCP 工具（mcp__context7__resolve-library-id/mcp__context7__get-library-docs）拉取文档，MCP 不可用时回退到npx --yes ctx7@latest library/docsCLI 方式。

评估规划器（gsd-eval-planner）回答"How will we know this AI system is working correctly?"，把领域评分要素转成可测量、有工具支撑的评估标准，写入 Sections 5–7。其默认工具取向（见 gsd-eval-planner 执行流）为：追踪默认Arize Phoenix（开源、可自托管、经 OpenTelemetry 与框架无关）、RAG 指标用RAGAS、CI 回归用Promptfoo、已入 LangChain 生态则用LangSmith覆盖 Phoenix。

消费端则有两处：规划时gsd-planner依据契约拆解任务；实施完成后 gsd-eval-auditor 以"对抗性姿态"回溯审计（详见下文第七节）。

三、Section 1 与 1b：系统分类与领域上下文

1. System Classification（系统分类）

该小节要求先把系统归类到固定枚举之一：

**System Type:** <!-- RAG | Multi-Agent | Conversational | Extraction | Autonomous Agent | Content Generation | Code Automation | Hybrid -->

随后用一段话描述系统做什么、谁在用、"good" 长什么样，并列出绝对不允许出错的 3~5 种关键失败模式（Critical Failure Modes）。这一节的用途贯穿全文：关键失败模式正是后续评估维度（Section 5）与在线护栏（Section 6）的输入。在 gsd-eval-planner 中，不同系统类型映射到不同的必备评估维度，例如：

无论何种类型，都要包含safety（用户面对）与task completion（agentic 场景）。

1b. Domain Context（领域上下文）

由gsd-domain-researcher研究产出，将评估策略锚定在领域专家知识上。需要填写的字段：

• Industry Vertical：行业垂直（healthcare / legal / finance / customer service / education / developer tooling / e-commerce 等）；
• User Population：谁用、在什么场景下用；
• Stakes Level：风险等级（Low / Medium / High / Critical）；
• Output Consequence：AI 输出被采取行动后下游会发生什么。

随后是四个子小节：

1. What Domain Experts Evaluate Against—— 领域专属评估要素，要求用从业者语言而非 AI 术语书写，格式为Dimension / Good (expert accepts) / Bad (expert flags) / Stakes / Source；
2. Known Failure Modes in This Domain—— 来自调研的领域专属失败模式（不是泛泛的幻觉，而是它在具体领域的表现形态）；
3. Regulatory / Compliance Context—— 相关法规约束，若确实没有则写 "None identified"；
4. Domain Expert Roles for Evaluation—— 领域专家在评估中的角色表（Role / Responsibility），如 "Senior practitioner → Dataset labeling / rubric calibration / production sampling"。

gsd-domain-researcher 的质量标准强调：Good/Bad 要具体到"两位领域专家会达成一致"，而不是笼统的 "accurate" 或 "helpful"；监管只列直接相关的，不罗列所有可能的法规；绝不捏造标准。

四、Section 2：框架决策

该小节记录选型结论，是契约中最"不可逆"的一环：

**Selected Framework:** <!-- e.g., LlamaIndex v0.10.x --> **Version:** <!-- Pin the version --> **Rationale:** 为什么这个框架适配系统类型、团队背景与生产需求 **Alternatives Considered:** 备选框架表（Framework | Ruled Out Because） **Vendor Lock-In Accepted:** <!-- Yes / No / Partial -->

仓库 ai-frameworks.md 提供了选型的决策矩阵参考：Quick Picks 速查表（如"生产级 RAG → LlamaIndex""复杂有状态分支工作流 → LangGraph""多智能体团队 → CrewAI"），以及按系统类型、团队规模与阶段、模型承诺三个维度划分的决策维度表。该参考文档还专门列出了 8 条反模式（Anti-Patterns），例如"用 LangChain 做简单聊天机器人""用 CrewAI 做复杂有状态工作流""对简单线性流程用 LangGraph"，并给出多框架组合玩法（如 LlamaIndex + Langfuse、LangGraph + LlamaIndex）。

gsd-framework-selector 的评分流程为：先剔除违反硬约束的框架，再按已作答维度打分（1–5），按用户声明的优先级加权，输出排名前 3。厂商锁定（Vendor Lock-In）必须被有意识地权衡并记录——选择器面试中专门询问模型供应商承诺（OpenAI / Anthropic / Gemini / Model-agnostic），并在推荐输出中标注hard_constraints与existing_ecosystem。

五、Section 3 与 4：框架速查与实现指导

3. Framework Quick Reference（框架速查）

由gsd-ai-researcher从官方文档提炼、按当前用例蒸馏，包含六部分：

• Installation：真实安装命令（# Install command(s)）；
• Core Imports：该用例的关键导入；
• Entry Point Pattern：可复制运行的最小工作示例；
• Key Abstractions：概念表（Concept | What It Is | When You Use It），3~5 行——开发者在写代码前必须理解的框架专属概念；
• Common Pitfalls：该框架 + 系统类型特有的坑（优先来自 GitHub issues 而非文档）；
• Recommended Project Structure：框架专属的目录布局示意。

gsd-ai-researcher 的质量标准包含：所有代码片段对已获取版本语法正确、导入匹配真实包结构、入口模式可直接复制运行、不得幻觉 API 方法（不确定时注明 "verify in docs"）、坑要具体（"能用 async 就用 async" 这类无效描述不算）。

4. Implementation Guidance（实现指导）

该小节针对当前用例给出落地参数，模板要求覆盖五个维度：

• Model Configuration：选用哪个模型、temperature、max tokens 及其他关键参数；
• Core Pattern：该框架 + 系统类型的核心实现模式（以带行内注释的代码片段呈现）；
• Tool Use：需要的工具/集成及配置方式；
• State Management：状态如何持久化、检索、更新；
• Context Window Strategy：该类型系统如何管理上下文上限。

4b. AI Systems Best Practices（AI 系统最佳实践）

同样由gsd-ai-researcher编写，是跨框架通用的横切模式，模板给出五个子主题：

1. Structured Outputs with Pydantic—— 输出模型定义、框架如何消费它（LangChain 的.with_structured_output()、instructor直连 API、LlamaIndex 的PydanticOutputParser、OpenAI 的response_format）、校验失败的重试逻辑（重试几次、记录什么、何时上抛）；
2. Async-First Design—— 框架的异步机制、最常见的错误（如在事件循环里调用asyncio.run()）、stream 与 await 的取舍（UX 场景用 stream，结构化输出校验场景用 await）；
3. Prompt Engineering Discipline—— system 与 user 提示词分离；few-shot 是内联还是动态检索；生产环境必须显式设置max_tokens，绝不无界；
4. Context Window Management—— RAG 场景的 reranking/截断、多智能体/对话场景的摘要压缩、自主 Agent 的框架级 compaction；
5. Cost and Latency Budget—— 预期规模下的单次调用成本估算、精确匹配 + 语义缓存、子任务（分类、路由、摘要）路由到更便宜模型。

六、Section 5：评估策略

Dimensions（维度表）

模板的维度表结构为：

| Dimension | Rubric (Pass/Fail or 1-5) | Measurement Approach | Priority | |-----------|--------------------------|---------------------|----------| | | | Code / LLM Judge / Human | Critical / High / Medium |

gsd-eval-planner 要求每个维度必须有具体评分标准，格式为：

PASS: {领域语言下的具体可接受行为} FAIL: {领域语言下的具体不可接受行为} Measurement: Code / LLM Judge / Human

测量方式按维度区分：Code-based（schema 校验、必填字段存在性、性能阈值、正则检查）；LLM judge（语气、推理质量、安全违规检测——必须先标定）；Human review（边界用例、LLM judge 标定、高利害抽样）。领域评分要素优先取 Section 1b，只有 1b 稀疏时才回退到通用维度。

Eval Tooling（评估工具）

需要填写 Primary Tool（如 RAGAS + Langfuse）、安装命令、以及CI/CD 集成命令——即在 Makefile / GitHub Actions 等流水线里执行评估的命令。gsd-eval-planner 会先扫描仓库已有工具（grep -r "langfuse|langsmith|arize|phoenix|braintrust|promptfoo|ragas"），检测到则沿用，否则使用意见化默认：Phoenix + RAGAS + Promptfoo，并附上 Phoenix 的 Python 接入代码（pip install arize-phoenix opentelemetry-sdk，px.launch_app()默认监听http://localhost:6006，再通过LlamaIndexInstrumentor().instrument()等接入）。

Reference Dataset（参考数据集）

模板要求明确：Size（如 "20 examples to start"）、Composition（覆盖哪些场景类型：关键路径、边界用例、失败模式）、Labeling（谁标注、如何标注：领域专家 / 经过标定的 LLM judge 等）。gsd-eval-planner 的底线是10 个样本起、生产 20 个，且数据集要在实现期间同步构建，而不是事后补。

七、Section 6 与 7：护栏与生产监控

6. Guardrails（护栏）

护栏决策的核心问题（见参考文档 ai-evals.md）："如果这个行为出错，对我的业务是否灾难性的？"回答 Yes → 在线护栏（实时、立即干预），回答 No → 离线飞轮（批量分析、持续改进）。护栏必须保持精简——每个都增加延迟。

模板的两种表格：

Online (Real-Time)：

| Guardrail | Trigger | Intervention | |-----------|---------|--------------| | | | Block / Escalate / Flag |

Offline (Flywheel)：

| Metric | Sampling Strategy | Action on Degradation | |--------|------------------|----------------------| | | | |

gsd-eval-planner 的分类方法：灾难性失败模式 → 在线护栏（每个请求都运行、实时、必须快）；质量信号 → 离线飞轮（抽样批处理，反馈改进回路）。用户面对的系统至少需要 1 条在线护栏。

7. Production Monitoring（生产监控）

模板要求填写四项：

• Tracing Tool：如 Langfuse self-hosted（默认取向为 Arize Phoenix，除非检测到已有工具）；
• Key Metrics to Track：生产环境要监控的 3~5 个指标；
• Alert Thresholds：何时告警/呼人；
• Smart Sampling Strategy：如何基于信号筛选交互供人工复核——按 ai-evals.md，抽样应向含可疑信号的交互倾斜（重试、异常长度、显式升级）。

八、Checklist 与质量门：模板如何被验证

模板末尾自带一份 18 项的完整 Checklist，逐项核对契约各章节是否填齐，例如：

• System type classified；Critical failure modes identified (≥ 3)；
• Domain context researched（Section 1b: vertical, stakes, expert criteria, failure modes）；
• Regulatory/compliance context identified or explicitly noted as none；
• Framework selected with rationale documented；Alternatives considered and ruled out；
• Framework quick reference written（install, imports, pattern, pitfalls）；
• AI systems best practices written（Section 4b: Pydantic, async, prompt discipline, context）；
• Evaluation dimensions grounded in domain rubric ingredients；每个维度有具体 rubric（Good/Bad in domain language）；
• Eval tooling selected —Arize Phoenix default confirmed or override noted；
• Reference dataset spec written（size ≥ 10, composition + labeling defined）；
• CI/CD eval integration specified；
• Online guardrails defined；Production monitoring configured（tracing tool + sampling strategy）。

这份 Checklist 不只是一纸清单——仓库测试 tests/ai-evals.test.cjs 中的TEMPLATE: AI-SPEC.md section completeness套件对其施加了硬性约束：模板必须包含 10 个必需章节标题（## 1. System Classification到## 7. Production Monitoring及## Checklist）、Checklist 条目 ≥ 10、Section 1b 含领域 rubric 表、Section 4b 含 Pydantic 指导、Section 6 含 Online/Offline 两张表。测试失败即意味着模板结构被破坏。

在工作流层面，ai-integration-phase 工作流 第 10 步还有一道验证门（validation gate）：读取完成的 AI-SPEC.md，检查 Section 2 有真实框架名（非占位符）、Section 1b 至少一条 Good/Bad/Stakes 要素、Section 3 有非空代码块、Section 4b 有 Pydantic 示例、Section 5 维度表至少一行、Section 6 至少一条护栏或显式 "N/A for internal tool" 说明、Checklist 勾选 ≥ 3 项。验证失败会指出缺失章节，并询问用户重跑特定步骤还是继续。

值得一提的还有一处工程细节：工作流第 7、8 步的排序注释明确要求gsd-ai-researcher与gsd-domain-researcher必须串行执行，且两者修改 AI-SPEC.md 时只准用 Edit 工具、禁用 Write 工具——因为 Write 会整文件覆盖、静默抹掉兄弟 Agent 的成果，而 Edit 只动目标行。仓库测试 bug-3096-ai-integration-phase-parallel-race.test.cjs 记录并防止了这一并行派发下的竞态问题（测试注释确认该缺陷曾在收尾阶段以 Write 调用整体替换了 AI-SPEC.md）。这提醒我们：当多个 Agent 共写同一契约文件时，写入工具的选择与执行顺序本身就是正确性的一部分。

九、消费端闭环：gsd-eval-auditor 如何回溯审计

契约的另一个消费端是gsd-eval-auditor（由/gsd:eval-review命令编排，见 commands/gsd/eval-review.md）。它实施完成后对 AI 阶段做追溯性评估覆盖审计，回答"已实现的系统真的交付了规划的评估策略吗"——而不是"看起来像"。

其打分标准（详见 gsd-eval-auditor）：

审计还会对五项基础设施打分（ok / partial / missing）：评估工具是否真正安装并被调用（而非仅列为依赖）、参考数据集是否满足规模与构成规格、CI/CD 集成命令是否存在、在线护栏是否实现在请求路径中（而非桩）、追踪工具是否包住真实 AI 调用。最终按公式量化：

coverage_score = covered_count / total_dimensions × 100 infra_score = (tooling + dataset + cicd + guardrails + tracing) / 5 × 100 overall_score = coverage_score × 0.6 + infra_score × 0.4

结论分档：80–100PRODUCTION READY；60–79NEEDS WORK；40–59SIGNIFICANT GAPS（不得部署）；0–39NOT IMPLEMENTED（回到 AI-SPEC.md 重新实现）。产出物是{phase_dir}/{padded_phase}-EVAL-REVIEW.md，含维度覆盖表、基础设施审计、关键缺口、按"必须修 / 应尽快修 / 锦上添花"分级的具体补救计划——这正好形成"规划（AI-SPEC）→ 实施 → 审计（EVAL-REVIEW）"的闭环。

十、上手路径：如何在你的 GSD 阶段中使用这份契约

1. 生成：在涉及 AI 系统的阶段执行/gsd:ai-integration-phase {N}（阶段号可省略，自动探测下一个未规划阶段）。工作流会先检查workflow.ai_integration_phase配置开关（可用/gsd:settings控制），再检查该阶段是否存在 CONTEXT.md，然后从模板cp一份{padded_phase}-AI-SPEC.md到阶段目录并驱动四个 Agent 填充。若 AI-SPEC.md 已存在，会询问 Update（以现有为基线重跑）/ View（展示后退出）/ Skip（保留现状退出）。
2. 消费：规划阶段执行/gsd:plan-phase {N}，planner 以 AI-SPEC.md 为依据拆解任务。
3. 审计：实施完成后执行/gsd:eval-review {N}（默认审计最后一个已完成阶段），由 gsd-eval-auditor 产出带分数与结论的 EVAL-REVIEW.md。
4. 参考素材：框架选型查阅 get-shit-done/references/ai-frameworks.md，评估体系查阅 get-shit-done/references/ai-evals.md（其中包含评估维度清单、工具选型表、开发全生命周期中的评估嵌入方式与 6 条常见坑）。

需要说明的是：AI-SPEC.md 模板本身是仓库内建的只读资产，使用方式是通过上述命令生成契约文件到各阶段的目录中，无需也不应改动模板文件本身。模板的完整性由 tests/ai-evals.test.cjs 持续守护，生成流程的章节写入纪律由 ai-integration-phase 工作流 的排序约束与 bug-3096 测试 共同保证——这正是"规范驱动"在 AI 工程化场景下的一个可复制的实践样本：先把"怎么做、如何评估、何时拦截、怎样监控"写成契约，再让代码与测试对契约负责。

【免费下载链接】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