gsd-core 领域研究员 Agent 实战指南：为 AI-SPEC Section 1b 产出专家级评估准则-育师

【免费下载链接】gsd-core

Git. Ship. Done - Core

项目地址：https://gitcode.com/gh_mirrors/ge/gsd-core

导读

本文基于 GSD（Git. Ship. Done）核心仓库中的领域研究员 Agent 规格文档 gsd-domain-researcher.md，系统讲解该 Agent 如何在 AI 集成阶段（ai-integration-phase）承担"业务领域研究"职责：从行业垂直、用户群体、风险等级与输出后果四个信号出发，产出领域专家认可的评估维度（Rubric Ingredients）、行业特有故障模式与合规上下文，最终写入 AI-SPEC.md 的 Section 1b。读完本文，你将掌握这套"先领域后指标"的评估前置流水线的完整输入契约、执行流程、输出契约与硬性写入纪律，并看到其背后的模板、编排工作流与测试佐证。

一、角色定位：回答"领域专家真正在意什么"

gsd-domain-researcher是一个由/gsd:ai-integration-phase编排器（orchestrator）派生的研究型子代理。它的核心使命不是研究技术框架，而是研究业务领域本身——即被构建的 AI 系统的真实世界应用场景。

按照规格文档的<role>定义，它的工作始终围绕一个核心问题展开：

"What do domain experts actually care about when evaluating this AI system?"（领域专家在评估这个 AI 系统时，真正关心的到底是什么？）

在此基础上，它要完成三件递进的事情：

调查业务领域（而非技术框架）；
揭示领域专家的评估标准、行业特有的故障模式、监管约束，以及该领域从业者眼中"做得好"（good）的样子；
在gsd-eval-planner将这些素材转成可度量的评分标准（rubrics）之前，把领域证据先沉淀到 AI-SPEC.md 的Section 1b。

与其他研究类 Agent 的分工边界

在 scripts/research-profiles.cjs 的 profile 表中，gsd-domain-researcher与gsd-ai-researcher形成互补：

gsd-ai-researcher：研究被选框架的官方文档，产出实现级指引（框架速查、核心模式、常见陷阱），写入 AI-SPEC.md 的 Section 3 与 Section 4/4b；
gsd-domain-researcher：研究业务领域，产出领域专家评估标准与合规上下文，写入 AI-SPEC.md 的Section 1b；
两者输出契约都在 AI-SPEC.md 上，但写入的是互不相交的章节。

在编排流水线中，它处于第 3 步（Step 3/4），前承框架选择器（gsd-framework-selector）与 AI 研究员（gsd-ai-researcher），后启评估规划器（gsd-eval-planner）。

二、编排上下文：ai-integration-phase 中的位置与调用契约

四步编排流水线

gsd-core/workflows/ai-integration-phase.md 定义了 AI 设计契约（AI-SPEC.md）的生成流程，gsd-domain-researcher在其中扮演固定角色：

步骤	Agent	产出
Step 1/4	gsd-framework-selector	框架选择、system_type、eval 关注点
Step 2/4	gsd-ai-researcher	Section 3（框架速查）、Section 4/4b（实现指引与最佳实践）
Step 3/4	gsd-domain-researcher	Section 1b（领域上下文与专家评估标准）
Step 4/4	gsd-eval-planner	Section 5/6/7（评估策略、护栏、生产监控）

编排器在 Step 8（## 8. Spawn gsd-domain-researcher）中派生该代理，并附带以下强制提示：

必须阅读~/.claude/agents/gsd-domain-researcher.md获取指令；
工具纪律（强制）：修改 AI-SPEC.md 时只能使用Edit工具，绝不使用Write——Write会整体替换文件，覆盖并行或串行兄弟代理已写入的内容；编辑前须确认目标章节仍是模板占位符；
传入<input>：system_type、phase_name、phase_goal、ai_spec_path。

串行执行与并发竞态规避

编排器文档中明确记录了工具层面的 last-writer-wins 竞态风险：Step 7（gsd-ai-researcher）与 Step 8（gsd-domain-researcher）虽然写入 AI-SPEC.md 的不同章节，但必须串行执行，必须等待 Step 7 完成后才能派生 Step 8。这一约束在 tests/execute-phase-wave.test.cjs 中有对应回归测试（如Step 8 gsd-domain-researcher prompt includes Edit-only tool discipline），防止并行派发导致约 40% 概率的相互覆盖（仓库注记 #3096）。

输入契约（`<input>`）

规格文档定义了该代理的入参，全部来自编排器上下文：

参数	含义
`system_type`	RAG \| Multi-Agent \| Conversational \| Extraction \| Autonomous \| Content \| Code \| Hybrid（八选一）
`phase_name`、`phase_goal`	来自 ROADMAP.md 的当前阶段名称与目标
`ai_spec_path`	AI-SPEC.md 的路径（部分已写入）
`context_path`	CONTEXT.md 路径（如存在）
`requirements_path`	REQUIREMENTS.md 路径（如存在）

此外还有一条硬性执行规则：如果 prompt 中包含<required_reading>，必须先读完列出的每一个文件，再开始任何其他工作。

三、执行流程：五步领域研究流水线

规格文档定义了五步执行流程，本文逐一步骤拆解其内在逻辑与产出要求。

步骤 1：extract_domain_signal（提取领域信号）

首先读取 AI-SPEC.md、CONTEXT.md、REQUIREMENTS.md，从中提取四个关键信号：

industry vertical（行业垂直）：如 healthcare、legal、finance、customer service 等；
user population（用户群体）；
stakes level（风险等级）；
output type（输出类型）。

若领域不明确，则从阶段名与目标推断，文档给出映射示例：

"contract review" → legal（法律）；
"support ticket" → customer service（客户服务）；
"medical intake" → healthcare（医疗保健）。

步骤 2：research_domain（领域定向检索）

运行 2～3 次定向检索，检索模板如下：

"{domain} AI system evaluation criteria site:arxiv.org OR site:research.google" "{domain} LLM failure modes production" "{domain} AI compliance requirements {current_year}"

需要从检索结果中提取四类素材：

从业者评估标准（practitioner eval criteria）——注意不是泛泛的"accuracy"（准确率），而是该领域实践者真正看重的具体行为；
生产部署中已知的故障模式（known failure modes from production deployments）；
直接相关的法规（directly relevant regulations，如 HIPAA、GDPR、FCA 等）；
领域专家角色（domain expert roles）。

步骤 3：synthesize_rubric_ingredients（合成评估维度原料）

产出3～5 个领域特定的评分维度构建块，每块按固定格式组织：

Dimension: {name in domain language, not AI jargon} Good (domain expert would accept): {specific description} Bad (domain expert would flag): {specific description} Stakes: Critical / High / Medium Source: {practitioner knowledge, regulation, or research}

规格文档给出了一个法律领域示例，直接展示了"维度语言必须贴合领域、而非 AI 术语"的要求：

Dimension: Citation precision（引用精确度） Good: Response cites the specific clause, section number, and jurisdiction （回答引用了具体条款、条号与司法辖区） Bad: Response states a legal principle without citing a source （回答陈述法律原则却不给出处） Stakes: Critical Source: Legal professional standards — unsourced legal advice constitutes malpractice risk （法律职业标准——无出处的法律意见构成执业事故风险）

这个示例揭示了核心方法论：Good/Bad 必须具体到两位领域专家能达成一致判断的程度，绝不能写成"accurate"或"helpful"这类无法判定的笼统措辞。

步骤 4：identify_domain_experts（识别评估参与专家）

明确哪些人应参与评估工作，覆盖四个环节：

数据集标注（dataset labeling）；
评分标准校准（rubric calibration）；
边界案例评审（edge case review）；
生产抽样（production sampling）。

同时规格文档给出了兜底原则：若内部工具不涉及受监管领域，"领域专家"即产品负责人（product owner）或资深团队成员。

步骤 5：write_section_1b（写入 Section 1b）

这是整个代理的交付步骤，包含文件写入契约（硬性规则）与Section 1b 输出模板两部分，详见本文第四、五节。

四、写入纪律：Write 契约与断点续写回退

规格文档对文件创建方式提出了极其严格的硬性规则，这是该文档最具工程实践价值的部分之一：

默认：单次Write调用完成整段写入——在大多数运行时上这是正确且可靠的；
不要在返回消息中回传 AI-SPEC.md 内容——编排器在你返回后从磁盘读取 AI-SPEC.md，它不会从你的返回消息中读取文件内容；返回消息只是简短确认，内容存于磁盘；
严禁使用Bash(cat << 'EOF')或 heredoc 创建文件——必须使用Write工具；
大文件/截断回退：某些运行时（如 OpenCode）会限制工具调用输出长度，过大的单次Write会在半途被截断，从而触发类似JSON Parse error: Expected '}'的工具错误。此时不要重试同样过大的调用（否则会无限循环），而应改为增量构建，保证任何单次工具调用都不携带完整负载：
- 先Write只含第一节的文件，以哨兵行结尾；
- Read文件后用Edit将哨兵替换为"下一节内容 + 哨兵"，逐节重复，每次Edit只写一节；
- 最后一节时，将哨兵替换为收尾内容，且不再保留尾部哨兵；
若写入仍然失败，必须在返回消息中暴露真实错误——不得静默回退为返回内容，那会向编排器隐藏失败，且造成同样的截断。

这套"Write 一次 + 哨兵分片续写"的协议，配合编排器层面对Edit工具的强制约束，构成了 AI-SPEC.md 这类共享设计契约文件在多代理流水线下的并发安全基础。

五、输出契约：AI-SPEC.md Section 1b 的标准模板

规格文档给出了必须写入 AI-SPEC.md 的 Section 1b 完整骨架，其结构与 gsd-core/templates/AI-SPEC.md 中的## 1b. Domain Context占位一致：

## 1b. Domain Context **Industry Vertical:** {vertical} **User Population:** {who uses this} **Stakes Level:** Low | Medium | High | Critical **Output Consequence:** {what happens downstream when the AI output is acted on} ### What Domain Experts Evaluate Against {3-5 rubric ingredients in Dimension/Good/Bad/Stakes/Source format} ### Known Failure Modes in This Domain {2-4 domain-specific failure modes — not generic hallucination} ### Regulatory / Compliance Context {Relevant constraints — or "None identified for this deployment context"} ### Domain Expert Roles for Evaluation | Role | Responsibility in Eval | |------|----------------------| | {role} | Reference dataset labeling / rubric calibration / production sampling | ### Research Sources - {sources used}

各字段要点：

Stakes Level为四档枚举：Low | Medium | High | Critical；
Output Consequence描述"AI 输出被采纳执行时下游会发生什么"，这是将风险等级落到具体业务影响的关键字段；
Known Failure Modes要求 2～4 个领域特有故障模式，明确禁止写成泛泛的"幻觉"（hallucination），而必须描述它在当前领域中的具体表现形态；
Regulatory / Compliance Context只列直接相关的约束，若确实没有则写 "None identified for this deployment context"；不得罗列一切可能的法规；
Domain Expert Roles以表格形式列角色与评估职责；
Research Sources列出本次研究实际使用的来源。

在 gsd-core/templates/AI-SPEC.md 中，Section 1b 头部注释明确标注：> Researched by gsd-domain-researcher. Grounds the evaluation strategy in domain expert knowledge.——即该章节的职责归属与定位是"把评估策略锚定在领域专家知识之上"。

六、质量底线与成功标准

质量标准（quality_standards）

规格文档对产出质量提出了五项硬约束：

Rubric 原料必须使用从业者语言，而非 AI/ML 术语；
Good/Bad 必须具体到两位领域专家能达成一致——不得用 "accurate" 或 "helpful" 这类词；
合规上下文只保留直接相关的部分——不要列举所有可能的法规；
若领域确实不明确，写一个最小化的章节，说明需向领域专家澄清什么；
绝不捏造标准——只呈现研究结果或业界公认的从业者知识。

成功标准（success_criteria）

清单式验收条件共 8 项，可作为该代理运行完成度的自检表：

从阶段产物中提取领域信号（Domain signal extracted from phase artifacts）
运行 2～3 次定向领域检索（2-3 targeted domain research queries run）
写出 3～5 个评分维度原料（Good/Bad/Stakes/Source 格式）
识别领域特有故障模式（非通用型）
识别或明确标注"无"合规/监管上下文
指定领域专家角色
AI-SPEC.md 的 Section 1b 已写入且非空
列出研究来源（Research sources listed）

七、与评估体系上下游的衔接：从领域语言到可度量指标

gsd-domain-researcher的产出并非终点，而是下游两个 Agent 的输入锚点。

下游消费者一：gsd-eval-planner（评估规划器）

agents/gsd-eval-planner.md 明确指示：领域研究员已经完成了 SME（领域主题专家）工作，规划器的职责是把 rubric 原料转成可度量标准，而不是重新推导领域上下文。其执行流程第一步（read_phase_context）要求通读 AI-SPEC.md 全文，其中特别点名 Section 1b 的领域 rubric 原料；第三步（write_rubrics）要求从 Section 1b 的领域 rubric 原料出发（而非通用维度），仅在 Section 1b 稀疏时才回退到 gsd-core/references/ai-evals.md 的通用维度。每条 rubric 按如下格式落地：

PASS: {specific acceptable behavior in domain language} FAIL: {specific unacceptable behavior in domain language} Measurement: Code / LLM Judge / Human

下游消费者二：gsd-eval-auditor（评估审计器）

agents/gsd-eval-auditor.md 则从反面闭环：在 AI 阶段实现完成后，它以对抗姿态（adversarial stance）扫描代码库，逐条对照 AI-SPEC.md 的评估计划，将每个评估维度评为COVERED / PARTIAL / MISSING，产出 EVAL-REVIEW.md。其强制分类规则（BLOCKER/WARNING）确保"文档写了"不等于"代码实现了"。这使得领域研究员产出的 Section 1b 不仅指导设计，还成为事后验收的对照基准。

理论底座：ai-evals.md 参考文档

gsd-core/references/ai-evals.md 是本代理的<required_reading>必读文件，提供了 rubric 设计的方法论支撑，其要点包括：

评估三组件：Input（影响系统的一切输入）、Expected（用 rubric 定义的良好行为）、Actual（系统实际产出）；
三种度量方式：基于代码的指标（确定性检查）、LLM 裁判（按 rubric 互评，须先与人工判断校准）、人工评估（校准/边界案例/高利害采样的金标准）——最有效的系统三者结合；
Rubric 设计原则：必须定义 (1) 被度量的维度；(2) 5 分制中 1/3/5 分或 pass/fail 的具体标准；(3) 领域特定的可接受/不可接受行为示例。文档特别强调："没有 rubric，LLM 裁判产出的只是噪音而非信号"；
"Helpfulness" 因领域而异：在房地产领域意味着清晰汇总房源，在医疗领域则意味着知道何时不该回答——这正是 domain-researcher 要把通用指标翻译成领域语言的依据。

评估前置的关键判断：Guardrail vs Flywheel

领域研究员提供的故障模式与风险等级，会直接参与下游"护栏 vs 飞轮"（Guardrail vs Flywheel）决策：若该行为出错对业务是灾难性的（Critical），则应作为在线护栏实时干预（拦截/升级/移交）；否则作为离线飞轮批量分析、持续改进。这一判定框架同样记录在 ai-evals.md 参考文档中。

八、仓库中的实现证据与测试佐证

编排与注册

gsd-core/workflows/ai-integration-phase.md 的 Step 8 负责派生本代理，并携带 Edit-only 工具纪律与串行顺序约束；
scripts/research-profiles.cjs 中的 profile 表将本代理的 name、description、color（purple）、tools、输出契约（AI-SPEC.md+Section 1b）作为逐字基准登记，用于gen-research-agents.cjs的一致性校验；
gsd-core/templates/AI-SPEC.md 提供 Section 1b 的初始占位结构。

测试佐证

gsd-core 测试目录中多个测试文件覆盖了该代理的存在性与编排约束：

tests/ai-evals.test.cjs：断言agents/gsd-domain-researcher.md存在；断言 ai-integration-phase 工作流引用全部 4 个 Agent；断言ai-evals.md参考文档非空且覆盖 Arize Phoenix 与 RAGAS 等工具默认值；
tests/execute-phase-wave.test.cjs：回归测试Step 8 gsd-domain-researcher prompt includes Edit-only tool discipline，验证编排器提示语中必须包含 Edit-only 纪律；
tests/research-agent-profiles.test.cjs：校验 agent 规格与 research-profiles.cjs 中 profile 表的一致性；
tests/untrusted-input-isolation.test.cjs 等隔离测试也将其列入受控代理清单，与规格文档引用的untrusted-input-boundary.md参考（gsd-core/references/planner-reversibility.md 中亦有引用）共同构成输入边界防护。

多运行时部署形态

本代理与全套 GSD 代理一样，按宿主运行时分发不同形态：完整版agents/gsd-domain-researcher.md、精简版 agents/gsd-domain-researcher.compact.md，以及针对 Codex、Kimi、Copilot 等运行时的.toml/.agent.md/.yaml变体（见 tests/fixtures/install-tree 下的安装树清单）。compact 版保留完整版的角色定义、输入契约、五步执行流程、Section 1b 模板、质量标准与成功标准，仅压缩叙事性说明——两个版本均由同一份 scripts/research-profiles.cjs profile 约束，确保行为一致。

结语

gsd-domain-researcher是 GSD AI 集成流水线中"领域知识 → 可度量评估"的关键翻译层：它用五步流程把模糊的业务背景提炼为领域专家语言书写的评分维度原料、行业特有故障模式与直接相关的合规约束，通过严格的 Write 契约与哨兵分片机制安全写入 AI-SPEC.md 的 Section 1b，再交由评估规划器转译为可执行的 PASS/FAIL 标准，最后由评估审计器在实现完成后对照验收。这条"先领域、后指标"的前置研究路径，正是避免"通用指标脱离业务语境"这一 AI 评估常见陷阱的工程化答案。