agent-spec-authoring

Category: Testing & Security | Uploader: ZhangHanDong | Downloads: 0 | Version: v1.0（Latest）
write spec, create spec, edit spec, new spec, spec authoring, task contract,
Changelog: Source: GitHub https://github.com/ZhangHanDong/agent-spec
Directory Structure

Current level: .claude/skills/agent-spec-authoring/
📁 references/
- 📄 patterns.md 6.9 KB
📄 SKILL.md 11.9 KB
SKILL.md

---
name: agent-spec-authoring
description: |
  CRITICAL: Use for writing and editing agent-spec .spec files. Triggers on:
  write spec, create spec, edit spec, new spec, spec authoring, task contract,
  .spec file, BDD scenario, acceptance criteria, completion criteria,
  test selector, boundary, constraint, intent, decision, out of scope,
  "how to write a spec", "spec format", "spec syntax", "contract quality",
  写 spec, 创建规格, 编辑合约, 任务合约, 验收标准, 完成条件,
  BDD 场景, 测试选择器, 约束, 意图, 决策, 边界, 排除范围,
  "怎么写 spec", "spec 格式", "spec 语法", "合约质量"
---

# Agent Spec Authoring

> **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

## 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".

## Quick Reference

| Section | Chinese Header | English Header | Purpose |
|---------|---------------|----------------|---------|
| 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 |

## Documentation

Refer to the local files for authoring patterns and examples:
- `./references/patterns.md` - Complete authoring patterns with examples

## 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

## Before Writing a Contract

Not every task needs a Contract. Ask yourself:

| Question | If 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.

## The Four Elements of a Contract

### 1. Intent — What and Why

One focused paragraph. Not a feature list — a clear statement of purpose.

```spec
## Intent

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

**Rules:**
- Focus on "what to do and why"
- Mention context (what already exists, where this fits)
- Keep it to 2-4 sentences

### 2. Decisions — Fixed Technical Choices

Already-decided choices. Not aspirational. Not options to explore.

```spec
## 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

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

Triple constraint: Allowed, Forbidden, Out-of-scope.

```spec
## Boundaries

### Allowed Changes
- crates/api/src/auth/**
- crates/api/tests/auth/**
- migrations/

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

## 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

### 4. Completion Criteria — Deterministic Pass/Fail

BDD scenarios with explicit test bindings.

**Critical principle: Exception scenarios >= happy path scenarios.**

```spec
## 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.

## Spec File Structure

### Frontmatter (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
---
```

### Three-Layer Inheritance

```
org.spec → project.spec → task.spec
```

| Layer | Scope | Example Content |
|-------|-------|-----------------|
| `org.spec` | Organization-wide | Coding standards, security rules, forbidden patterns |
| `project.spec` | Project-level | Tech stack decisions, API conventions, test requirements |
| `task.spec` | Single task | Intent, boundaries, specific acceptance criteria |

Constraints and decisions are **inherited downward**. Task specs inherit from project, which inherits from org.

## BDD Step Keywords

| English | Chinese | Usage |
|---------|---------|-------|
| `Given` | `假设` | Precondition |
| `When` | `当` | Action |
| `Then` | `那么` | Expected result |
| `And` | `并且` | Additional step (same type as previous) |
| `But` | `但是` | Negative additional step |

## Test Selector Patterns

### Simple selector

```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
```

### Chinese equivalents

```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
```

## Boundary Patterns

### Machine-enforced (path globs)

```spec
### Allowed Changes
- crates/spec-parser/**
- tests/parser_contract.rs
```

BoundariesVerifier checks actual changed files against these globs.

### Natural language prohibitions

```spec
### 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.

## Common Errors

| Lint Warning | Cause | Fix |
|-------------|-------|-----|
| `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 verified | Use observable assertions: "returns error code X" |
| `coverage` | Constraint with no covering scenario | Add a scenario that exercises the constraint |
| `determinism` | Non-deterministic step wording | Remove "should", "might"; use definitive assertions |
| `implicit-dep` | Missing `Test:` selector on scenario | Add `Test: test_name` or structured `Test:` block |
| `sycophancy` | Bug-finding bias language | Remove "find all bugs", "must find issues" |

## Authoring Checklist

Before handing a Contract to an Agent, verify:

| # | Check | Why |
|---|-------|-----|
| 1 | Intent is 2-4 focused sentences | Agent needs clear direction, not a novel |
| 2 | Decisions are specific (tech, version, params) | Agent shouldn't be choosing technology |
| 3 | Boundaries have path globs for Allowed Changes | Enables mechanical enforcement |
| 4 | Exception scenarios >= happy path scenarios | Forces edge-case thinking upfront |
| 5 | Every scenario has a `Test:` selector | Required for TestVerifier to run |
| 6 | Steps use deterministic wording | "returns 201" not "should return 201" |
| 7 | `agent-spec lint` score >= 0.7 | Quality gate before Agent starts |

## Deprecated Patterns (Don't Use)

| Deprecated | Use Instead | Reason |
|------------|-------------|--------|
| Scenarios without `Test:` | Always add `Test:` selector | Required for mechanical verification |
| Vague boundaries like "be careful" | Specific path globs or prohibitions | Must be mechanically checkable |
| "should" / "might" in steps | Definitive "returns" / "is" / "becomes" | Non-deterministic wording fails lint |
| `brief` command to preview | `contract` command | `brief` is a legacy alias |
| Only happy path scenarios | Include exception paths (>= happy) | Edge cases are where bugs live |

## 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

## 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.
Comments 0
Latest | Hot
Please login before commenting.
No comments yet. Be the first one!
agent-spec-authoring

Directory Structure

SKILL.md

Report

Notice
