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本篇围绕 GSDget-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开始前锁定四件事框架选型Framework selection—— 含理由与备选方案实现指导Implementation guidance—— 来自官方文档的正确语法、模式与坑领域上下文Domain context—— 从业者视角的评估要素、失败模式、监管约束评估策略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即步骤Agent负责写入模板的章节1/4gsd-framework-selector产出选型结果供 Section 2 填充2/4gsd-ai-researcherSections 3–4b框架速查、实现指导、AI 最佳实践3/4gsd-domain-researcherSection 1b领域上下文4/4gsd-eval-plannerSections 5–7评估策略、护栏、生产监控框架选择器gsd-framework-selector是流水线的起点它会先扫描代码库中的package.json、pyproject.toml等技术信号再进行一次 ≤6 问的面试系统类型、模型供应商、开发阶段、语言、优先级、硬约束最后按 ai-frameworks.md 中的决策矩阵打分输出结构化的FRAMEWORK_RECOMMENDATIONprimary / 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 ctx7latest 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 中不同系统类型映射到不同的必备评估维度例如系统类型必备评估维度RAGcontext faithfulness、hallucination、answer relevance、retrieval precision、source citationMulti-Agenttask decomposition、inter-agent handoff、goal completion、loop detectionConversationaltone/style、safety、instruction following、escalation accuracyExtractionschema compliance、field accuracy、format validityAutonomoussafety guardrails、tool use correctness、cost/token adherence、task completionCodecorrectness、safety、test pass rate、instruction following无论何种类型都要包含safety用户面对与task completionagentic 场景。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 / CriticalOutput ConsequenceAI 输出被采取行动后下游会发生什么。随后是四个子小节What Domain Experts Evaluate Against—— 领域专属评估要素要求用从业者语言而非 AI 术语书写格式为Dimension / Good (expert accepts) / Bad (expert flags) / Stakes / SourceKnown Failure Modes in This Domain—— 来自调研的领域专属失败模式不是泛泛的幻觉而是它在具体领域的表现形态Regulatory / Compliance Context—— 相关法规约束若确实没有则写 None identifiedDomain 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 It3~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 PracticesAI 系统最佳实践同样由gsd-ai-researcher编写是跨框架通用的横切模式模板给出五个子主题Structured Outputs with Pydantic—— 输出模型定义、框架如何消费它LangChain 的.with_structured_output()、instructor直连 API、LlamaIndex 的PydanticOutputParser、OpenAI 的response_format、校验失败的重试逻辑重试几次、记录什么、何时上抛Async-First Design—— 框架的异步机制、最常见的错误如在事件循环里调用asyncio.run()、stream 与 await 的取舍UX 场景用 stream结构化输出校验场景用 awaitPrompt Engineering Discipline—— system 与 user 提示词分离few-shot 是内联还是动态检索生产环境必须显式设置max_tokens绝不无界Context Window Management—— RAG 场景的 reranking/截断、多智能体/对话场景的摘要压缩、自主 Agent 的框架级 compactionCost 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-basedschema 校验、必填字段存在性、性能阈值、正则检查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-sdkpx.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 classifiedCritical failure modes identified (≥ 3)Domain context researchedSection 1b: vertical, stakes, expert criteria, failure modesRegulatory/compliance context identified or explicitly noted as noneFramework selected with rationale documentedAlternatives considered and ruled outFramework quick reference writteninstall, imports, pattern, pitfallsAI systems best practices writtenSection 4b: Pydantic, async, prompt discipline, contextEvaluation dimensions grounded in domain rubric ingredients每个维度有具体 rubricGood/Bad in domain languageEval tooling selected —Arize Phoenix default confirmed or override notedReference dataset spec writtensize ≥ 10, composition labeling definedCI/CD eval integration specifiedOnline guardrails definedProduction monitoring configuredtracing 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状态标准COVERED存在实现针对 rubric 行为可运行自动化或有文档的人工流程PARTIAL存在但不完整——缺 rubric 精度、未自动化、或有已知缺口MISSING该维度无任何实现审计还会对五项基础设施打分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 READY60–79NEEDS WORK40–59SIGNIFICANT GAPS不得部署0–39NOT IMPLEMENTED回到 AI-SPEC.md 重新实现。产出物是{phase_dir}/{padded_phase}-EVAL-REVIEW.md含维度覆盖表、基础设施审计、关键缺口、按必须修 / 应尽快修 / 锦上添花分级的具体补救计划——这正好形成规划AI-SPEC→ 实施 → 审计EVAL-REVIEW的闭环。十、上手路径如何在你的 GSD 阶段中使用这份契约生成在涉及 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保留现状退出。消费规划阶段执行/gsd:plan-phase {N}planner 以 AI-SPEC.md 为依据拆解任务。审计实施完成后执行/gsd:eval-review {N}默认审计最后一个已完成阶段由 gsd-eval-auditor 产出带分数与结论的 EVAL-REVIEW.md。参考素材框架选型查阅 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 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本篇围绕 GSDget-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开始前锁定四件事框架选型Framework selection—— 含理由与备选方案实现指导Implementation guidance—— 来自官方文档的正确语法、模式与坑领域上下文Domain context—— 从业者视角的评估要素、失败模式、监管约束评估策略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即步骤Agent负责写入模板的章节1/4gsd-framework-selector产出选型结果供 Section 2 填充2/4gsd-ai-researcherSections 3–4b框架速查、实现指导、AI 最佳实践3/4gsd-domain-researcherSection 1b领域上下文4/4gsd-eval-plannerSections 5–7评估策略、护栏、生产监控框架选择器gsd-framework-selector是流水线的起点它会先扫描代码库中的package.json、pyproject.toml等技术信号再进行一次 ≤6 问的面试系统类型、模型供应商、开发阶段、语言、优先级、硬约束最后按 ai-frameworks.md 中的决策矩阵打分输出结构化的FRAMEWORK_RECOMMENDATIONprimary / 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 ctx7latest 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 中不同系统类型映射到不同的必备评估维度例如系统类型必备评估维度RAGcontext faithfulness、hallucination、answer relevance、retrieval precision、source citationMulti-Agenttask decomposition、inter-agent handoff、goal completion、loop detectionConversationaltone/style、safety、instruction following、escalation accuracyExtractionschema compliance、field accuracy、format validityAutonomoussafety guardrails、tool use correctness、cost/token adherence、task completionCodecorrectness、safety、test pass rate、instruction following无论何种类型都要包含safety用户面对与task completionagentic 场景。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 / CriticalOutput ConsequenceAI 输出被采取行动后下游会发生什么。随后是四个子小节What Domain Experts Evaluate Against—— 领域专属评估要素要求用从业者语言而非 AI 术语书写格式为Dimension / Good (expert accepts) / Bad (expert flags) / Stakes / SourceKnown Failure Modes in This Domain—— 来自调研的领域专属失败模式不是泛泛的幻觉而是它在具体领域的表现形态Regulatory / Compliance Context—— 相关法规约束若确实没有则写 None identifiedDomain 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 It3~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 PracticesAI 系统最佳实践同样由gsd-ai-researcher编写是跨框架通用的横切模式模板给出五个子主题Structured Outputs with Pydantic—— 输出模型定义、框架如何消费它LangChain 的.with_structured_output()、instructor直连 API、LlamaIndex 的PydanticOutputParser、OpenAI 的response_format、校验失败的重试逻辑重试几次、记录什么、何时上抛Async-First Design—— 框架的异步机制、最常见的错误如在事件循环里调用asyncio.run()、stream 与 await 的取舍UX 场景用 stream结构化输出校验场景用 awaitPrompt Engineering Discipline—— system 与 user 提示词分离few-shot 是内联还是动态检索生产环境必须显式设置max_tokens绝不无界Context Window Management—— RAG 场景的 reranking/截断、多智能体/对话场景的摘要压缩、自主 Agent 的框架级 compactionCost 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-basedschema 校验、必填字段存在性、性能阈值、正则检查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-sdkpx.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 classifiedCritical failure modes identified (≥ 3)Domain context researchedSection 1b: vertical, stakes, expert criteria, failure modesRegulatory/compliance context identified or explicitly noted as noneFramework selected with rationale documentedAlternatives considered and ruled outFramework quick reference writteninstall, imports, pattern, pitfallsAI systems best practices writtenSection 4b: Pydantic, async, prompt discipline, contextEvaluation dimensions grounded in domain rubric ingredients每个维度有具体 rubricGood/Bad in domain languageEval tooling selected —Arize Phoenix default confirmed or override notedReference dataset spec writtensize ≥ 10, composition labeling definedCI/CD eval integration specifiedOnline guardrails definedProduction monitoring configuredtracing 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状态标准COVERED存在实现针对 rubric 行为可运行自动化或有文档的人工流程PARTIAL存在但不完整——缺 rubric 精度、未自动化、或有已知缺口MISSING该维度无任何实现审计还会对五项基础设施打分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 READY60–79NEEDS WORK40–59SIGNIFICANT GAPS不得部署0–39NOT IMPLEMENTED回到 AI-SPEC.md 重新实现。产出物是{phase_dir}/{padded_phase}-EVAL-REVIEW.md含维度覆盖表、基础设施审计、关键缺口、按必须修 / 应尽快修 / 锦上添花分级的具体补救计划——这正好形成规划AI-SPEC→ 实施 → 审计EVAL-REVIEW的闭环。十、上手路径如何在你的 GSD 阶段中使用这份契约生成在涉及 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保留现状退出。消费规划阶段执行/gsd:plan-phase {N}planner 以 AI-SPEC.md 为依据拆解任务。审计实施完成后执行/gsd:eval-review {N}默认审计最后一个已完成阶段由 gsd-eval-auditor 产出带分数与结论的 EVAL-REVIEW.md。参考素材框架选型查阅 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考