Back to Details

agent-spec-authoring

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Agent Spec Authoring

Agent Spec 编写指南

Version: 3.1.0 | Last Updated: 2026-03-08
You are an expert at writing agent-spec Task Contracts. Help users by:
  • Creating specs: Scaffold new 
    .spec
    files with correct structure
  • Editing specs: Improve intent, constraints, boundaries, scenarios
  • Writing scenarios: BDD-style with proper test selectors and step tables
  • Debugging specs: Fix lint warnings, improve quality scores
  • Self-hosting: Maintain specs for the agent-spec project itself
版本: 3.1.0 | 最后更新: 2026-03-08
你是编写agent-spec任务合约的专家，可从以下方面为用户提供帮助：
  • 创建spec: 按照正确结构搭建新的
    .spec
    文件框架
  • 编辑spec: 优化意图、约束、边界、场景等内容
  • 编写场景: 输出符合BDD风格的内容，附带正确的测试选择器和步骤表格
  • 调试spec: 修复lint警告，提升质量评分
  • 自托管维护: 维护agent-spec项目本身的spec文件

Core Philosophy

核心理念

A Contract is not a vague Issue — it's a precise specification that shifts the review point:
Traditional:  Human reviews 500 lines of code diff (slow, error-prone)
agent-spec:   Human writes 50-80 lines of Contract (fast, high-value)
              Machine verifies code against Contract (deterministic)
Writing a Contract is the highest-value human activity in the agent-spec workflow. You're defining "what is correct" — the machine handles "is the code correct".
合约不是模糊的Issue——它是精准的规范，能前移审核节点：
传统模式:  人工审核500行代码diff（速度慢、易出错）
agent-spec: 人工编写50-80行合约（速度快、价值高）
            机器对照合约验证代码（结果确定）
编写合约是agent-spec工作流中价值最高的人工活动：你只需要定义“什么是正确的”，机器会负责判断“代码是否正确”。

Quick Reference

快速参考

SectionChinese HeaderEnglish HeaderPurpose
Intent
## 意图
## Intent
What to do and why
Constraints
## 约束
## Constraints
Must / Must NOT rules
Decisions
## 已定决策
/ 
## 决策
## Decisions
Fixed technical choices
Boundaries
## 边界
## Boundaries
Allowed / Forbidden / Out-of-scope
Acceptance Criteria
## 验收标准
/ 
## 完成条件
## Acceptance Criteria
/ 
## Completion Criteria
BDD scenarios
Out of Scope
## 排除范围
## Out of Scope
Explicitly excluded items
模块中文表头英文表头用途
意图
## 意图
## Intent
要做什么、为什么做
约束
## 约束
## Constraints
必须遵守/禁止的规则
已定决策
## 已定决策
/ 
## 决策
## Decisions
已确定的技术选型
边界
## 边界
## Boundaries
允许/禁止/超出范围的内容
验收标准
## 验收标准
/ 
## 完成条件
## Acceptance Criteria
/ 
## Completion Criteria
BDD场景
排除范围
## 排除范围
## Out of Scope
明确不包含的内容

Documentation

文档说明

Refer to the local files for authoring patterns and examples:
  • ./references/patterns.md
    - Complete authoring patterns with examples
编写模式和示例请参考本地文件：
  • ./references/patterns.md
    - 完整的编写模式及示例

IMPORTANT: Documentation Completeness Check

重要：文档完整性检查

Before answering questions, Claude MUST:
  1. Read 
    ./references/patterns.md
    for authoring patterns
  2. If file read fails: Inform user "references/patterns.md is missing, answering from SKILL.md patterns"
  3. Still answer based on SKILL.md patterns + built-in knowledge
回答问题前，Claude必须：
  1. 读取
    ./references/patterns.md
    获取编写模式
  2. 如果文件读取失败：告知用户“references/patterns.md 不存在，将基于SKILL.md的模式进行回答”
  3. 基于SKILL.md的模式+内置知识完成回答

Before Writing a Contract

编写合约前的判断

Not every task needs a Contract. Ask yourself:
QuestionIf No
Can I define what "done" looks like?Vibe code first, write Contract later
Can I write at least one deterministic test?Not Contract-ready yet
Is the scope bounded enough to list Allowed Changes?Split into smaller tasks
Do I know the key technical decisions?Do a spike/prototype first
If all "yes" — proceed with authoring. If not, doing exploratory work first is the right call.
不是所有任务都需要编写合约，先问自己这些问题：
问题答案为否的处理方式
我能明确定义“完成”的标准吗？先写demo代码，后续再补合约
我能写出至少一个结果确定的测试用例吗？暂不适合编写合约
范围是否足够清晰，可以列出所有允许的变更？拆分成更小的任务
我知道核心的技术决策吗？先做技术调研/原型验证
如果所有答案都是“是”，再开始编写合约。如果不是，先做探索性工作是更合理的选择。

The Four Elements of a Contract

合约的四大核心要素

1. Intent — What and Why

1. 意图——做什么、为什么

One focused paragraph. Not a feature list — a clear statement of purpose.
spec
undefined
一段聚焦的描述，不是功能列表，而是清晰的目的陈述。
spec
undefined

Intent

Intent

为现有的认证模块添加用户注册 endpoint。新用户通过邮箱+密码注册， 注册成功后发送验证邮件。这是用户体系的第一步，后续会在此基础上 添加登录和密码重置。

**Rules:**
- Focus on "what to do and why"
- Mention context (what already exists, where this fits)
- Keep it to 2-4 sentences
为现有的认证模块添加用户注册 endpoint。新用户通过邮箱+密码注册， 注册成功后发送验证邮件。这是用户体系的第一步，后续会在此基础上 添加登录和密码重置。

**规则:**
- 聚焦“要做什么、为什么做”
- 说明上下文（现有基础、当前任务的定位）
- 控制在2-4句话

2. Decisions — Fixed Technical Choices

2. 决策——已确定的技术选型

Already-decided choices. Not aspirational. Not options to explore.
spec
undefined
已经敲定的选择，不是预期目标，也不是待探索的选项。
spec
undefined

Decisions

Decisions

  • 路由: POST /api/v1/auth/register
  • 密码哈希: bcrypt, cost factor = 12
  • 验证 Token: crypto.randomUUID(), 存数据库, 24h 过期
  • 邮件: 使用现有 EmailService，不新建

**Rules:**
- Only choices that are **already fixed** — not "we should consider..."
- Include specific technologies, versions, parameters
- Agent follows these without questioning — they're not open for debate
  • 路由: POST /api/v1/auth/register
  • 密码哈希: bcrypt, cost factor = 12
  • 验证 Token: crypto.randomUUID(), 存数据库, 24h 过期
  • 邮件: 使用现有 EmailService，不新建

**规则:**
- 只放**已经确定**的选择，不要出现“我们应该考虑…”这类表述
- 包含具体的技术、版本、参数
- Agent会严格遵循这些决策，不需要再讨论

3. Boundaries — What to Touch, What Not to Touch

3. 边界——允许修改什么、禁止修改什么

Triple constraint: Allowed, Forbidden, Out-of-scope.
spec
undefined
三重约束：允许变更、禁止变更、超出范围。
spec
undefined

Boundaries

Boundaries

Allowed Changes

Allowed Changes

  • crates/api/src/auth/**
  • crates/api/tests/auth/**
  • migrations/
  • crates/api/src/auth/**
  • crates/api/tests/auth/**
  • migrations/

Forbidden

Forbidden

  • 不要添加新的 npm/cargo 依赖
  • 不要修改现有的登录 endpoint
  • 不要在注册流程中创建 session
  • 不要添加新的 npm/cargo 依赖
  • 不要修改现有的登录 endpoint
  • 不要在注册流程中创建 session

Out of Scope

Out of Scope

  • 登录功能
  • 密码重置
  • OAuth 第三方登录

**Rules:**
- Path globs (`crates/auth/**`) are **mechanically enforced** by BoundariesVerifier
- Natural language prohibitions are checked by lint but not file-path enforced
- Out of Scope prevents scope creep — Agent knows what NOT to attempt
  • 登录功能
  • 密码重置
  • OAuth 第三方登录

**规则:**
- 路径通配符（`crates/auth/**`）会被边界验证器**自动强制校验**
- 自然语言的禁止规则会经过lint检查，但不会做文件路径层面的强制校验
- 排除范围可以避免范围蔓延，让Agent明确知道不需要尝试哪些内容

4. Completion Criteria — Deterministic Pass/Fail

4. 完成条件——结果确定的通过/不通过标准

BDD scenarios with explicit test bindings.
Critical principle: Exception scenarios >= happy path scenarios.
spec
undefined
附带明确测试绑定的BDD场景。
核心原则：异常场景数量 >= 正常路径场景数量。
spec
undefined

Completion Criteria

Completion Criteria

场景: 注册成功 ← 1 happy path 测试: test_register_returns_201 假设 不存在邮箱为 "alice@example.com" 的用户 当 客户端提交注册请求: | 字段 | 值 | | email | alice@example.com | | password | Str0ng!Pass#2026 | 那么 响应状态码为 201 并且 响应体包含 "user_id"
场景: 重复邮箱被拒绝 ← exception path 1 测试: test_register_rejects_duplicate_email 假设 已存在邮箱为 "alice@example.com" 的用户 当 客户端提交相同邮箱的注册请求 那么 响应状态码为 409
场景: 弱密码被拒绝 ← exception path 2 测试: test_register_rejects_weak_password 假设 不存在邮箱为 "bob@example.com" 的用户 当 客户端提交密码为 "123" 的注册请求 那么 响应状态码为 400
场景: 缺少必填字段 ← exception path 3 测试: test_register_rejects_missing_fields 当 客户端提交缺少 email 字段的注册请求 那么 响应状态码为 400

This forces you to think through edge cases **before coding begins**. The Agent can't skip error handling because each exception path has a bound test.
场景: 注册成功 ← 1个正常路径 测试: test_register_returns_201 假设 不存在邮箱为 "alice@example.com" 的用户 当 客户端提交注册请求: | 字段 | 值 | | email | alice@example.com | | password | Str0ng!Pass#2026 | 那么 响应状态码为 201 并且 响应体包含 "user_id"
场景: 重复邮箱被拒绝 ← 异常路径1 测试: test_register_rejects_duplicate_email 假设 已存在邮箱为 "alice@example.com" 的用户 当 客户端提交相同邮箱的注册请求 那么 响应状态码为 409
场景: 弱密码被拒绝 ← 异常路径2 测试: test_register_rejects_weak_password 假设 不存在邮箱为 "bob@example.com" 的用户 当 客户端提交密码为 "123" 的注册请求 那么 响应状态码为 400
场景: 缺少必填字段 ← 异常路径3 测试: test_register_rejects_missing_fields 当 客户端提交缺少 email 字段的注册请求 那么 响应状态码为 400

这会强制你在编码开始前就考虑所有边界情况，Agent不能跳过异常处理，因为每个异常路径都有绑定的测试。

Spec File Structure

Spec 文件结构

Frontmatter (YAML)

前置元数据（YAML）

spec
spec: task           # Level: org, project, task
name: "Task Name"   # Human-readable name
inherits: project    # Parent spec (optional)
tags: [feature, api] # Tags for filtering
---
spec
spec: task           # 层级: org, project, task
name: "Task Name"   # 易读的名称
inherits: project    # 父级spec（可选）
tags: [feature, api] # 用于过滤的标签
---

Three-Layer Inheritance

三层继承体系

org.spec → project.spec → task.spec
LayerScopeExample Content
org.spec
Organization-wideCoding standards, security rules, forbidden patterns
project.spec
Project-levelTech stack decisions, API conventions, test requirements
task.spec
Single taskIntent, boundaries, specific acceptance criteria
Constraints and decisions are inherited downward. Task specs inherit from project, which inherits from org.
org.spec → project.spec → task.spec
层级作用范围示例内容
org.spec
公司/组织全局编码规范、安全规则、禁止的模式
project.spec
项目级别技术栈决策、API规范、测试要求
task.spec
单个任务意图、边界、具体的验收标准
约束和决策会向下继承：任务spec继承项目spec的规则，项目spec继承组织spec的规则。

BDD Step Keywords

BDD 步骤关键词

EnglishChineseUsage
Given
假设
Precondition
When
当
Action
Then
那么
Expected result
And
并且
Additional step (same type as previous)
But
但是
Negative additional step
英文中文用途
Given
假设
前置条件
When
当
执行动作
Then
那么
预期结果
And
并且
同类型的额外步骤
But
但是
否定的额外步骤

Test Selector Patterns

测试选择器模式

Simple selector

简单选择器

spec
Scenario: Happy path
  Test: test_happy_path
  Given precondition
  When action
  Then result
spec
Scenario: Happy path
  Test: test_happy_path
  Given precondition
  When action
  Then result

Structured selector (cross-crate)

结构化选择器（跨包）

spec
Scenario: Cross-crate verification
  Test:
    Package: spec-gateway
    Filter: test_contract_prompt_format
  Given a task spec
  When verified
  Then passes
spec
Scenario: Cross-crate verification
  Test:
    Package: spec-gateway
    Filter: test_contract_prompt_format
  Given a task spec
  When verified
  Then passes

Chinese equivalents

中文等价写法

spec
场景: 正常路径
  测试: test_happy_path

场景: 跨包验证
  测试:
    包: spec-gateway
    过滤: test_contract_prompt_format
spec
场景: 正常路径
  测试: test_happy_path

场景: 跨包验证
  测试:
    包: spec-gateway
    过滤: test_contract_prompt_format

Step Tables

步骤表格

For structured inputs, use tables instead of inventing custom prose:
spec
Scenario: Batch validation
  Test: test_batch_validation
  Given the following input records:
    | name  | email           | valid |
    | Alice | alice@test.com  | true  |
    | Bob   | invalid         | false |
  When the validator processes the batch
  Then "1" record passes and "1" record fails
对于结构化输入，使用表格代替自定义的文字描述：
spec
Scenario: Batch validation
  Test: test_batch_validation
  Given the following input records:
    | name  | email           | valid |
    | Alice | alice@test.com  | true  |
    | Bob   | invalid         | false |
  When the validator processes the batch
  Then "1" record passes and "1" record fails

Boundary Patterns

边界模式

Machine-enforced (path globs)

机器强制校验（路径通配符）

spec
undefined
spec
undefined

Allowed Changes

Allowed Changes

  • crates/spec-parser/**
  • tests/parser_contract.rs

BoundariesVerifier checks actual changed files against these globs.
  • crates/spec-parser/**
  • tests/parser_contract.rs

边界验证器会对比实际变更的文件和这些通配符规则进行校验。

Natural language prohibitions

自然语言禁止规则

spec
undefined
spec
undefined

Forbidden

Forbidden

  • Do not break the existing JSON shape
  • Do not introduce .unwrap()

Checked by lint, not mechanically enforced against file paths.

**Use both when needed.** Path globs for file-level control, natural language for behavioral prohibitions.
  • Do not break the existing JSON shape
  • Do not introduce .unwrap()

会经过lint检查，但不会做文件路径层面的强制校验。

**需要时可以同时使用两种模式**：路径通配符用于文件级别的控制，自然语言用于行为层面的约束。

Common Errors

常见错误

Lint WarningCauseFix
vague-verb
"handle", "manage", "process", "处理"Be specific: "validate email format" not "handle email"
unquantified
"fast", "efficient", "应该快速"Add metrics: "respond within 200ms" not "respond quickly"
testability
Steps that can't be mechanically verifiedUse observable assertions: "returns error code X"
coverage
Constraint with no covering scenarioAdd a scenario that exercises the constraint
determinism
Non-deterministic step wordingRemove "should", "might"; use definitive assertions
implicit-dep
Missing 
Test:
selector on scenario		Add 
Test: test_name
or structured 
Test:
block
sycophancy
Bug-finding bias languageRemove "find all bugs", "must find issues"
Lint 警告原因修复方式
vague-verb
使用了“handle”、“manage”、“process”、“处理”这类模糊动词表述更具体：用“验证邮箱格式”代替“处理邮箱”
unquantified
使用了“fast”、“efficient”、“应该快速”这类无量化的描述添加指标：用“200ms内响应”代替“快速响应”
testability
步骤无法被自动校验使用可观测的断言：比如“返回错误码X”
coverage
约束没有对应的覆盖场景新增一个验证该约束的场景
determinism
步骤表述结果不确定移除“应该”、“可能”这类表述，使用明确的断言
implicit-dep
场景缺少
Test:
选择器		添加
Test: 测试名称
或者结构化的
Test:
块
sycophancy
存在偏向找bug的表述移除“找出所有bug”、“必须发现问题”这类内容

Authoring Checklist

编写检查清单

Before handing a Contract to an Agent, verify:
#CheckWhy
1Intent is 2-4 focused sentencesAgent needs clear direction, not a novel
2Decisions are specific (tech, version, params)Agent shouldn't be choosing technology
3Boundaries have path globs for Allowed ChangesEnables mechanical enforcement
4Exception scenarios >= happy path scenariosForces edge-case thinking upfront
5Every scenario has a 
Test:
selector		Required for TestVerifier to run
6Steps use deterministic wording"returns 201" not "should return 201"
7
agent-spec lint
score >= 0.7		Quality gate before Agent starts
把合约交给Agent之前，请确认：
序号检查项原因
1意图是2-4句聚焦的描述Agent需要清晰的方向，而不是长篇大论
2决策内容具体（技术、版本、参数）Agent不应该负责选择技术方案
3边界部分的允许变更有对应的路径通配符支持自动强制校验
4异常场景数量 >= 正常路径场景数量强制提前考虑边界情况
5每个场景都有
Test:
选择器		测试验证器运行的必要条件
6步骤使用结果确定的表述用“返回201”代替“应该返回201”
7
agent-spec lint
得分 >= 0.7		Agent开始工作前的质量门槛

Deprecated Patterns (Don't Use)

已弃用模式（不要使用）

DeprecatedUse InsteadReason
Scenarios without 
Test:
Always add 
Test:
selector		Required for mechanical verification
Vague boundaries like "be careful"Specific path globs or prohibitionsMust be mechanically checkable
"should" / "might" in stepsDefinitive "returns" / "is" / "becomes"Non-deterministic wording fails lint
brief
command to preview
contract
command
brief
is a legacy alias
Only happy path scenariosInclude exception paths (>= happy)Edge cases are where bugs live
已弃用替代方案原因
没有
Test:
的场景		始终添加
Test:
选择器		自动校验的必要条件
“小心修改”这类模糊边界具体的路径通配符或者禁止规则必须支持自动校验
步骤里的“应该”/“可能”明确的“返回”/“是”/“变为”不确定的表述会导致lint不通过
用
brief
命令预览		用
contract
命令
brief
是遗留别名
只包含正常路径的场景包含异常场景（数量>=正常路径）边界情况是bug高发区

Self-Hosting Rules

自托管规则

When authoring specs for the 
agent-spec
project itself:
  • Put task specs under 
    specs/
  • Roadmap specs go in 
    specs/roadmap/
    , promote to 
    specs/
    when active
  • Update tests when DSL or verification behavior changes
  • Preserve the four verdicts: 
    pass
    , 
    fail
    , 
    skip
    , 
    uncertain
  • Do not let a task spec rely on implicit test-name matching
为
agent-spec
项目本身编写spec时：
  • 任务spec放在
    specs/
    目录下
  • 路线图spec放在
    specs/roadmap/
    ，激活后移动到
    specs/
    目录
  • DSL或者验证行为变更时更新测试
  • 保留四种判定结果：
    pass
    、
    fail
    、
    skip
    、
    uncertain
  • 不要让任务spec依赖隐式的测试名称匹配

Escalation

升级流程

Authoring → Implementation: Switch to 
agent-spec-tool-first
after the Contract is drafted and passes 
agent-spec lint
with score >= 0.7.
Implementation → Authoring: Switch back here if the Agent discovers during implementation that:
  • A missing exception path needs to be added to Completion Criteria
  • A Boundary is too restrictive and needs expanding
  • A Decision was wrong and needs changing
Update the Contract first, re-lint, then resume implementation. The Contract is a living document until the task is stamped.
编写 → 实现：合约编写完成且
agent-spec lint
得分>=0.7后，切换到
agent-spec-tool-first
模式。
实现 → 编写：如果Agent在实现过程中发现以下问题，切回当前模式：
  • 完成条件里缺少异常路径需要补充
  • 边界过于严格需要扩大范围
  • 决策错误需要修改
先更新合约，重新lint通过后再继续实现。合约是活文档，直到任务被标记完成前都可以修改。