Back to Details

doc-tspec

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

doc-tspec

doc-tspec

Purpose

用途

Create Test Specifications (TSPEC) - Layer 10 artifact in the SDD workflow that defines test cases for Test-Driven Development (TDD) between SPEC (Layer 9) and TASKS (Layer 11).
Layer: 10
Upstream: BRD (Layer 1), PRD (Layer 2), EARS (Layer 3), BDD (Layer 4), ADR (Layer 5), SYS (Layer 6), REQ (Layer 7), CTR (Layer 8), SPEC (Layer 9)
Downstream Artifacts: TASKS (Layer 11), Code (Layer 12)
创建测试规范（TSPEC）——SDD工作流中的第10层工件，用于在SPEC（第9层）和TASKS（第11层）之间定义测试驱动开发（TDD）的测试用例。
Layer: 10
上游工件: BRD（第1层）、PRD（第2层）、EARS（第3层）、BDD（第4层）、ADR（第5层）、SYS（第6层）、REQ（第7层）、CTR（第8层）、SPEC（第9层）
下游工件: TASKS（第11层）、代码（第12层）

Prerequisites

前置条件

Upstream Artifact Verification (CRITICAL)

上游工件验证（关键）

Before creating this document, you MUST:
  1. List existing upstream artifacts:
    bash
    ls docs/01_BRD/ docs/02_PRD/ docs/03_EARS/ docs/04_BDD/ docs/05_ADR/ docs/06_SYS/ docs/07_REQ/ docs/08_CTR/ docs/09_SPEC/ 2>/dev/null
  2. Reference only existing documents in traceability tags
  3. Use 
    null
     only when upstream artifact type genuinely doesn't exist
  4. NEVER use placeholders like 
    BRD-XXX
    or 
    TBD
  5. Do NOT create missing upstream artifacts - skip functionality instead
Before creating TSPEC, read:
  1. Shared Standards: 
    .claude/skills/doc-flow/SHARED_CONTENT.md
  2. Upstream SPEC: Read technical specifications (PRIMARY SOURCE)
  3. Upstream REQ: Read atomic requirements
  4. Template by Type:
    • UTEST: 
      ai_dev_flow/10_TSPEC/UTEST/UTEST-MVP-TEMPLATE.md
    • ITEST: 
      ai_dev_flow/10_TSPEC/ITEST/ITEST-MVP-TEMPLATE.md
    • STEST: 
      ai_dev_flow/10_TSPEC/STEST/STEST-MVP-TEMPLATE.md
    • FTEST: 
      ai_dev_flow/10_TSPEC/FTEST/FTEST-MVP-TEMPLATE.md
  5. TSPEC README: 
    ai_dev_flow/10_TSPEC/README.md
在创建本文档前，您必须：
  1. 列出已有的上游工件:
    bash
    ls docs/01_BRD/ docs/02_PRD/ docs/03_EARS/ docs/04_BDD/ docs/05_ADR/ docs/06_SYS/ docs/07_REQ/ docs/08_CTR/ docs/09_SPEC/ 2>/dev/null
  2. 在可追溯性标签中仅引用已存在的文档
  3. 只有当对应的上游工件类型确实不存在时，才使用
    null
  4. 绝不使用
    BRD-XXX
    或
    TBD
    这类占位符
  5. 不要创建缺失的上游工件——而是跳过相关功能
创建TSPEC前，请阅读：
  1. 共享标准: 
    .claude/skills/doc-flow/SHARED_CONTENT.md
  2. 上游SPEC: 阅读技术规范（主要来源）
  3. 上游REQ: 阅读原子需求
  4. 按类型选择模板:
    • UTEST: 
      ai_dev_flow/10_TSPEC/UTEST/UTEST-MVP-TEMPLATE.md
    • ITEST: 
      ai_dev_flow/10_TSPEC/ITEST/ITEST-MVP-TEMPLATE.md
    • STEST: 
      ai_dev_flow/10_TSPEC/STEST/STEST-MVP-TEMPLATE.md
    • FTEST: 
      ai_dev_flow/10_TSPEC/FTEST/FTEST-MVP-TEMPLATE.md
  5. TSPEC说明文档: 
    ai_dev_flow/10_TSPEC/README.md

When to Use This Skill

何时使用该技能

Use 
doc-tspec
when:
  • Have completed BRD through SPEC (Layers 1-9)
  • Ready to define test cases before implementation
  • Following Test-Driven Development workflow
  • Need to specify unit, integration, smoke, or functional tests
  • You are at Layer 10 of the SDD workflow
在以下场景使用
doc-tspec
:
  • 已完成从BRD到SPEC的所有层级（第1-9层）
  • 准备在实现前定义测试用例
  • 遵循测试驱动开发工作流
  • 需要指定单元、集成、冒烟或功能测试
  • 处于SDD工作流的第10层

Reserved ID Exemption (TSPEC-00_*)

保留ID豁免（TSPEC-00_*）

Scope: Documents with reserved ID 
000
are FULLY EXEMPT from validation.
Pattern: 
TSPEC-00_*.md
, 
{TYPE}-00_*.md
(where TYPE is UTEST/ITEST/STEST/FTEST)
Document Types:
  • Index documents (
    TSPEC-00_index.md
    )
  • Traceability matrix templates (
    TSPEC-00_TRACEABILITY_MATRIX-TEMPLATE.md
    )
  • Glossaries, registries, checklists
Rationale: Reserved ID 000 documents are framework infrastructure (indexes, templates, reference materials), not project artifacts requiring traceability or quality gates.
Validation Behavior: Skip all checks when filename matches 
TSPEC-00_*
or 
{TYPE}-00_*
pattern.
范围: 保留ID为
000
的文档完全豁免验证。
格式: 
TSPEC-00_*.md
, 
{TYPE}-00_*.md
（其中TYPE为UTEST/ITEST/STEST/FTEST）
文档类型:
  • 索引文档（
    TSPEC-00_index.md
    ）
  • 可追溯性矩阵模板（
    TSPEC-00_TRACEABILITY_MATRIX-TEMPLATE.md
    ）
  • 术语表、注册表、检查清单
理由: 保留ID 000的文档属于框架基础设施（索引、模板、参考资料），而非需要可追溯性或质量门的项目工件。
验证规则: 当文件名匹配
TSPEC-00_*
或
{TYPE}-00_*
格式时，跳过所有检查。

Element ID Format (MANDATORY)

元素ID格式（强制）

Pattern: 
TSPEC.{DOC_NUM}.{ELEM_TYPE}.{SEQ}
(4 segments, dot-separated)
Element TypeCodeTest CategoryExample
Unit Test Case40UTESTTSPEC.01.40.01
Integration Test Case41ITESTTSPEC.01.41.01
Smoke Test Case42STESTTSPEC.01.42.01
Functional Test Case43FTESTTSPEC.01.43.01
REMOVED PATTERNS - Do NOT use legacy formats:
  • TC-XXX
    - Use 
    TSPEC.NN.TT.SS
    instead
  • UT-XXX
    - Use 
    TSPEC.NN.40.SS
    instead
  • IT-XXX
    - Use 
    TSPEC.NN.41.SS
    instead
  • ST-XXX
    - Use 
    TSPEC.NN.42.SS
    instead
  • FT-XXX
    - Use 
    TSPEC.NN.43.SS
    instead
Reference: doc-naming skill for complete element type codes.
格式: 
TSPEC.{DOC_NUM}.{ELEM_TYPE}.{SEQ}
（4个段，用点分隔）
元素类型代码测试分类示例
单元测试用例40UTESTTSPEC.01.40.01
集成测试用例41ITESTTSPEC.01.41.01
冒烟测试用例42STESTTSPEC.01.42.01
功能测试用例43FTESTTSPEC.01.43.01
已弃用格式 - 请勿使用旧格式:
  • TC-XXX
    - 请使用
    TSPEC.NN.TT.SS
    替代
  • UT-XXX
    - 请使用
    TSPEC.NN.40.SS
    替代
  • IT-XXX
    - 请使用
    TSPEC.NN.41.SS
    替代
  • ST-XXX
    - 请使用
    TSPEC.NN.42.SS
    替代
  • FT-XXX
    - 请使用
    TSPEC.NN.43.SS
    替代
参考: 文档命名技能获取完整的元素类型代码。

TSPEC Types Overview

TSPEC类型概述

TypeCodeAbbreviationPurposePrimary Source
Unit Test40UTESTIndividual function/method testsREQ (L7), SPEC (L9)
Integration Test41ITESTComponent interaction testsCTR (L8), SYS (L6)
Smoke Test42STESTPost-deployment health checksEARS (L3), BDD (L4)
Functional Test43FTESTSystem behavior validationSYS (L6)
Note: Acceptance tests remain in BDD (Layer 4), not duplicated in TSPEC.
类型代码缩写用途主要来源
单元测试40UTEST单个函数/方法测试REQ（第7层）、SPEC（第9层）
集成测试41ITEST组件交互测试CTR（第8层）、SYS（第6层）
冒烟测试42STEST部署后健康检查EARS（第3层）、BDD（第4层）
功能测试43FTEST系统行为验证SYS（第6层）
注意: 验收测试仍保留在BDD（第4层），请勿在TSPEC中重复。

TSPEC-Specific Guidance

TSPEC专属指南

1. Test Document Structure

1. 测试文档结构

Directory Structure:
docs/10_TSPEC/
├── UTEST/
│   ├── UTEST-01_{component}_unit.md
│   └── UTEST-02_{component}_unit.md
├── ITEST/
│   ├── ITEST-01_{component}_integration.md
│   └── ITEST-02_{component}_integration.md
├── STEST/
│   ├── STEST-01_{component}_smoke.md
│   └── STEST-02_{component}_smoke.md
├── FTEST/
│   ├── FTEST-01_{component}_functional.md
│   └── FTEST-02_{component}_functional.md
└── TSPEC-00_TRACEABILITY_MATRIX.md
目录结构:
docs/10_TSPEC/
├── UTEST/
│   ├── UTEST-01_{component}_unit.md
│   └── UTEST-02_{component}_unit.md
├── ITEST/
│   ├── ITEST-01_{component}_integration.md
│   └── ITEST-02_{component}_integration.md
├── STEST/
│   ├── STEST-01_{component}_smoke.md
│   └── STEST-02_{component}_smoke.md
├── FTEST/
│   ├── FTEST-01_{component}_functional.md
│   └── FTEST-02_{component}_functional.md
└── TSPEC-00_TRACEABILITY_MATRIX.md

2. Required Sections (All TSPEC Types)

2. 所有TSPEC类型的必填章节

Document Control (MANDATORY - First section):
ItemDetails
StatusDraft / Review / Approved / Implemented
Version0.1.0
Date CreatedYYYY-MM-DD
Last UpdatedYYYY-MM-DD
Author[Author name]
Component[Component/module name]
SPEC ReferenceSPEC-NN
Coverage TargetXX%
TASKS-Ready Score[XX]% (Target: see type-specific)
Core Sections:
  1. Document Control: Metadata and version tracking
  2. Test Scope: Component under test, categories, dependencies
  3. Test Case Index: Summary table of all test cases
  4. Test Case Details: Full specification per test case
  5. Coverage Matrix: REQ/SPEC coverage tracking
  6. Traceability: Cumulative upstream/downstream tags
文档控制（强制 - 第一章）:
项详情
状态草稿 / 评审中 / 已批准 / 已实现
版本0.1.0
创建日期YYYY-MM-DD
最后更新日期YYYY-MM-DD
作者[作者姓名]
组件[组件/模块名称]
SPEC参考SPEC-NN
覆盖目标XX%
任务就绪分数[XX]%（目标：见各类型专属要求）
核心章节:
  1. 文档控制: 元数据和版本追踪
  2. 测试范围: 被测组件、分类、依赖关系
  3. 测试用例索引: 所有测试用例的汇总表
  4. 测试用例详情: 每个测试用例的完整规范
  5. 覆盖矩阵: REQ/SPEC覆盖追踪
  6. 可追溯性: 累计的上游/下游标签

3. Test Case Format

3. 测试用例格式

Each test case MUST include:
markdown
undefined
每个测试用例必须包含:
markdown
undefined

TSPEC.NN.TT.SS: [Test Name]

TSPEC.NN.TT.SS: [测试名称]

Category: [Logic] | [State] | [Validation] | [Edge] | [Integration] | [Critical Path]
Traceability:
  • @req: REQ.NN.27.XX
  • @spec: SPEC-NN (Section X.Y)
Input/Output Table:
InputExpected OutputNotes
param1="valid"
True
Happy path
param1=""
ValidationError
Empty input
Pseudocode:
GIVEN valid input parameters
WHEN function_under_test(param1) is called
THEN result equals expected_output
AND no side effects occur
Error Cases:
Error ConditionExpected Behavior
Invalid input typeRaise 
TypeError
undefined
分类: [逻辑] | [状态] | [验证] | [边界] | [集成] | [关键路径]
可追溯性:
  • @req: REQ.NN.27.XX
  • @spec: SPEC-NN (Section X.Y)
输入/输出表:
输入预期输出说明
param1="valid"
True
正常路径
param1=""
ValidationError
空输入
伪代码:
GIVEN valid input parameters
WHEN function_under_test(param1) is called
THEN result equals expected_output
AND no side effects occur
错误场景:
错误条件预期行为
无效输入类型抛出
TypeError
undefined

4. Type-Specific Requirements

4. 各类型专属要求

UTEST (Unit Tests - Code 40)

UTEST（单元测试 - 代码40）

TASKS-Ready Score Target: >=90%
Required Tags: 
@req
, 
@spec
Test Categories: [Logic], [State], [Validation], [Edge]
Coverage Requirements:
  • Function coverage: >=90%
  • Branch coverage: >=80%
  • REQ element coverage: >=90%
任务就绪分数目标: >=90%
必填标签: 
@req
, 
@spec
测试分类: [逻辑], [状态], [验证], [边界]
覆盖要求:
  • 函数覆盖率: >=90%
  • 分支覆盖率: >=80%
  • REQ元素覆盖率: >=90%

ITEST (Integration Tests - Code 41)

ITEST（集成测试 - 代码41）

TASKS-Ready Score Target: >=85%
Required Tags: 
@ctr
, 
@sys
, 
@spec
Test Categories: [Integration], [Contract], [Sequence]
Requirements:
  • Sequence diagrams for complex interactions
  • CTR contract validation
  • Mock/stub strategy documented
任务就绪分数目标: >=85%
必填标签: 
@ctr
, 
@sys
, 
@spec
测试分类: [集成], [契约], [序列]
要求:
  • 复杂交互需提供序列图
  • 验证CTR契约
  • 记录Mock/Stub策略

STEST (Smoke Tests - Code 42)

STEST（冒烟测试 - 代码42）

TASKS-Ready Score Target: 100%
Required Tags: 
@ears
, 
@bdd
, 
@req
Test Categories: [Critical Path], [Health Check], [Deployment]
Requirements:
  • Total execution time <5 minutes
  • Rollback procedures documented
  • Critical path coverage 100%
任务就绪分数目标: 100%
必填标签: 
@ears
, 
@bdd
, 
@req
测试分类: [关键路径], [健康检查], [部署]
要求:
  • 总执行时间<5分钟
  • 记录回滚流程
  • 关键路径覆盖率100%

FTEST (Functional Tests - Code 43)

FTEST（功能测试 - 代码43）

TASKS-Ready Score Target: >=85%
Required Tags: 
@sys
, 
@threshold
Test Categories: [Functional], [Scenario], [End-to-End]
Requirements:
  • SYS requirement coverage
  • Threshold registry references for performance assertions
任务就绪分数目标: >=85%
必填标签: 
@sys
, 
@threshold
测试分类: [功能], [场景], [端到端]
要求:
  • 覆盖SYS需求
  • 引用阈值注册表以定义性能断言

5. Coverage Matrix Format

5. 覆盖矩阵格式

markdown
undefined
markdown
undefined

Coverage Matrix

覆盖矩阵

REQ IDREQ TitleTest IDsCoverage
REQ.NN.27.01[Title]TSPEC.NN.40.01, TSPEC.NN.40.03Covered
REQ.NN.27.02[Title]TSPEC.NN.40.02Covered
REQ.NN.27.03[Title]-NOT COVERED
Coverage Summary:
  • Total REQ elements: [N]
  • Covered: [N]
  • Coverage: [XX]%
undefined
REQ IDREQ标题测试ID覆盖状态
REQ.NN.27.01[标题]TSPEC.NN.40.01, TSPEC.NN.40.03已覆盖
REQ.NN.27.02[标题]TSPEC.NN.40.02已覆盖
REQ.NN.27.03[标题]-未覆盖
覆盖汇总:
  • 总REQ元素数: [N]
  • 已覆盖数: [N]
  • 覆盖率: [XX]%
undefined

Cumulative Tagging Requirements

累计标签要求

Layer 10 (TSPEC): Must include tags from Layers 1-9
Tag Count: 8 required tags (minimum), 9 if CTR created
第10层（TSPEC）: 必须包含第1-9层的标签
标签数量: 至少8个必填标签，若已创建CTR则为9个

Element Type Codes for Cumulative Tags

累计标签的元素类型代码

ArtifactElement TypeCodeExample
BRDBusiness Requirement01BRD.01.01.03
PRDProduct Feature07PRD.01.07.02
EARSEARS Statement25EARS.01.25.01
BDDScenario14BDD.01.14.01
ADRDocument reference-ADR-033 (dash notation)
SYSSystem Requirement26SYS.01.26.01
REQAtomic Requirement27REQ.01.27.01
SPECDocument reference-SPEC-01 (dash notation)
Minimum (8 tags - CTR skipped):
markdown
undefined
工件元素类型代码示例
BRD业务需求01BRD.01.01.03
PRD产品功能07PRD.01.07.02
EARSEARS声明25EARS.01.25.01
BDD场景14BDD.01.14.01
ADR文档引用-ADR-033（短横线格式）
SYS系统需求26SYS.01.26.01
REQ原子需求27REQ.01.27.01
SPEC文档引用-SPEC-01（短横线格式）
最少标签（8个 - 跳过CTR）:
markdown
undefined

Traceability

可追溯性

Required Tags (Cumulative Tagging Hierarchy - Layer 10):
@brd: BRD.01.01.03 @prd: PRD.01.07.02 @ears: EARS.01.25.01 @bdd: BDD.01.14.01 @adr: ADR-033, ADR-045 @sys: SYS.01.26.01 @req: REQ.01.27.01 @spec: SPEC-01

**Maximum (9 tags - CTR included)**:
```markdown
@brd: BRD.01.01.03
@prd: PRD.01.07.02
@ears: EARS.01.25.01
@bdd: BDD.01.14.01
@adr: ADR-033, ADR-045
@sys: SYS.01.26.01
@req: REQ.01.27.01
@ctr: CTR-01
@spec: SPEC-01
必填标签（累计标签层级 - 第10层）:
@brd: BRD.01.01.03 @prd: PRD.01.07.02 @ears: EARS.01.25.01 @bdd: BDD.01.14.01 @adr: ADR-033, ADR-045 @sys: SYS.01.26.01 @req: REQ.01.27.01 @spec: SPEC-01

**最多标签（9个 - 包含CTR）**:
```markdown
@brd: BRD.01.01.03
@prd: PRD.01.07.02
@ears: EARS.01.25.01
@bdd: BDD.01.14.01
@adr: ADR-033, ADR-045
@sys: SYS.01.26.01
@req: REQ.01.27.01
@ctr: CTR-01
@spec: SPEC-01

Tag Format Convention (By Design)

标签格式约定（设计如此）

The SDD framework uses two distinct notation systems for cross-references:
NotationFormatArtifactsPurpose
DashTYPE-NNADR, SPEC, CTRTechnical artifacts - references to files/documents
DotTYPE.NN.TT.SSBRD, PRD, EARS, BDD, SYS, REQ, TSPECHierarchical artifacts - references to elements inside documents
Key Distinction:
  • @adr: ADR-033
    - Points to the document 
    ADR-033_risk_limit_enforcement.md
  • @brd: BRD.17.01.01
    - Points to element 01.01 inside document 
    BRD-017.md
SDD框架使用两种不同的符号系统进行交叉引用:
符号格式工件用途
短横线TYPE-NNADR, SPEC, CTR技术工件 - 引用文件/文档
点TYPE.NN.TT.SSBRD, PRD, EARS, BDD, SYS, REQ, TSPEC层级化工件 - 引用文档内的元素
关键区别:
  • @adr: ADR-033
    - 指向文档
    ADR-033_risk_limit_enforcement.md
  • @brd: BRD.17.01.01
    - 指向文档
    BRD-017.md
    内的元素01.01

Validation Checks

验证检查

Tier 1: Errors (Blocking)

一级：错误（阻塞）

CheckDescription
CHECK 1Filename format valid ({TYPE}-NN_{slug}.md)
CHECK 2YAML frontmatter present with required fields
CHECK 3Document Control table complete
CHECK 4All required sections present
CHECK 5Element ID format compliance (TSPEC.NN.TT.SS)
CHECK 6Element type code matches document type (40/41/42/43)
CHECK 7All 8 required traceability tags present
CHECK 8Parent SPEC reference valid and file exists
检查项描述
检查1文件名格式有效（{TYPE}-NN_{slug}.md）
检查2存在包含必填字段的YAML前置元数据
检查3文档控制表填写完整
检查4所有必填章节存在
检查5元素ID格式合规（TSPEC.NN.TT.SS）
检查6元素类型代码与文档类型匹配（40/41/42/43）
检查7所有8个必填可追溯性标签存在
检查8父SPEC引用有效且文件存在

Tier 2: Warnings

二级：警告

CheckDescription
CHECK W1I/O table present for each test case
CHECK W2Pseudocode provided for complex tests
CHECK W3Coverage matrix complete
CHECK W4TASKS-Ready Score meets type-specific target
CHECK W5Error cases documented
检查项描述
检查W1每个测试用例都有输入/输出表
检查W2复杂测试提供伪代码
检查W3覆盖矩阵填写完整
检查W4任务就绪分数达到各类型专属目标
检查W5错误场景已记录

Tier 3: Info

三级：信息

CheckDescription
CHECK I1Test fixtures documented
CHECK I2Mock strategy specified
CHECK I3Performance targets defined (FTEST)
检查项描述
检查I1测试夹具已记录
检查I2指定了Mock策略
检查I3定义了性能目标（FTEST）

Creation Process

创建流程

Step 1: Identify Test Type Needed

步骤1：确定所需测试类型

Determine which TSPEC type(s) to create based on requirements:
  • UTEST for unit testing individual functions
  • ITEST for component integration testing
  • STEST for deployment health verification
  • FTEST for system behavior validation
根据需求确定要创建的TSPEC类型:
  • UTEST用于单个函数的单元测试
  • ITEST用于组件集成测试
  • STEST用于部署健康验证
  • FTEST用于系统行为验证

Step 2: Read Upstream Artifacts

步骤2：阅读上游工件

Focus on SPEC (Layer 9) and REQ (Layer 7) as primary sources.
重点阅读SPEC（第9层）和REQ（第7层）作为主要来源。

Step 3: Reserve ID Number

步骤3：保留ID编号

Check 
docs/10_TSPEC/{TYPE}/
for next available ID number.
ID Numbering Convention: Start with 2 digits and expand only as needed.
  • Correct: UTEST-01, ITEST-02, STEST-99
  • Incorrect: UTEST-001, ITEST-009 (extra leading zero not required)
查看
docs/10_TSPEC/{TYPE}/
获取下一个可用的ID编号。
ID编号约定: 从2位数字开始，仅在需要时扩展。
  • 正确格式: UTEST-01, ITEST-02, STEST-99
  • 错误格式: UTEST-001, ITEST-009（不需要多余的前导零）

Step 4: Create TSPEC File

步骤4：创建TSPEC文件

File naming: 
docs/10_TSPEC/{TYPE}/{TYPE}-NN_{slug}.md
Examples:
  • docs/10_TSPEC/UTEST/UTEST-01_auth_service_unit.md
  • docs/10_TSPEC/ITEST/ITEST-01_api_integration.md
  • docs/10_TSPEC/STEST/STEST-01_deployment_smoke.md
  • docs/10_TSPEC/FTEST/FTEST-01_order_processing_functional.md
文件名: 
docs/10_TSPEC/{TYPE}/{TYPE}-NN_{slug}.md
示例:
  • docs/10_TSPEC/UTEST/UTEST-01_auth_service_unit.md
  • docs/10_TSPEC/ITEST/ITEST-01_api_integration.md
  • docs/10_TSPEC/STEST/STEST-01_deployment_smoke.md
  • docs/10_TSPEC/FTEST/FTEST-01_order_processing_functional.md

Step 5: Fill Document Control Section

步骤5：填写文档控制章节

Complete metadata including SPEC Reference and TASKS-Ready Score.
完成元数据，包括SPEC参考和任务就绪分数。

Step 6: Define Test Scope

步骤6：定义测试范围

Document component under test, test categories, and dependencies.
记录被测组件、测试分类和依赖关系。

Step 7: Create Test Case Index

步骤7：创建测试用例索引

Summary table listing all test cases with priority.
汇总表列出所有测试用例及其优先级。

Step 8: Write Test Case Details

步骤8：编写测试用例详情

For each test case:
  • Assign Element ID (TSPEC.NN.TT.SS)
  • Define category
  • Add traceability tags
  • Create I/O table
  • Write pseudocode
  • Document error cases
对于每个测试用例:
  • 分配元素ID（TSPEC.NN.TT.SS）
  • 定义分类
  • 添加可追溯性标签
  • 创建输入/输出表
  • 编写伪代码
  • 记录错误场景

Step 9: Build Coverage Matrix

步骤9：构建覆盖矩阵

Map test cases to REQ elements, calculate coverage percentage.
将测试用例映射到REQ元素，计算覆盖率。

Step 10: Add Cumulative Tags

步骤10：添加累计标签

Include all 8-9 upstream tags (@brd through @spec).
包含所有8-9个上游标签（@brd至@spec）。

Step 11: Create/Update Traceability Matrix

步骤11：创建/更新可追溯性矩阵

MANDATORY: Update 
docs/10_TSPEC/TSPEC-00_TRACEABILITY_MATRIX.md
强制: 更新
docs/10_TSPEC/TSPEC-00_TRACEABILITY_MATRIX.md

Step 12: Validate TSPEC

步骤12：验证TSPEC

bash
undefined
bash
undefined

Type-specific validation

各类型专属验证

python ai_dev_flow/10_TSPEC/scripts/validate_utest.py docs/10_TSPEC/UTEST/UTEST-01_.md python ai_dev_flow/10_TSPEC/scripts/validate_itest.py docs/10_TSPEC/ITEST/ITEST-01_.md python ai_dev_flow/10_TSPEC/scripts/validate_stest.py docs/10_TSPEC/STEST/STEST-01_.md python ai_dev_flow/10_TSPEC/scripts/validate_ftest.py docs/10_TSPEC/FTEST/FTEST-01_.md
python ai_dev_flow/10_TSPEC/scripts/validate_utest.py docs/10_TSPEC/UTEST/UTEST-01_.md python ai_dev_flow/10_TSPEC/scripts/validate_itest.py docs/10_TSPEC/ITEST/ITEST-01_.md python ai_dev_flow/10_TSPEC/scripts/validate_stest.py docs/10_TSPEC/STEST/STEST-01_.md python ai_dev_flow/10_TSPEC/scripts/validate_ftest.py docs/10_TSPEC/FTEST/FTEST-01_.md

Combined quality score

综合质量分数

bash ai_dev_flow/10_TSPEC/scripts/validate_tspec_quality_score.sh docs/10_TSPEC/
bash ai_dev_flow/10_TSPEC/scripts/validate_tspec_quality_score.sh docs/10_TSPEC/

Cumulative tagging validation

累计标签验证

python ai_dev_flow/scripts/validate_tags_against_docs.py
--artifact UTEST-01
--expected-layers brd,prd,ears,bdd,adr,sys,req,spec
--strict
undefined
python ai_dev_flow/scripts/validate_tags_against_docs.py
--artifact UTEST-01
--expected-layers brd,prd,ears,bdd,adr,sys,req,spec
--strict
undefined

Step 13: Commit Changes

步骤13：提交变更

Commit TSPEC file and traceability matrix.
提交TSPEC文件和可追溯性矩阵。

Validation

验证

Automated Validation

自动化验证

bash
undefined
bash
undefined

All TSPEC types

所有TSPEC类型

bash ai_dev_flow/10_TSPEC/scripts/validate_all_tspec.sh docs/10_TSPEC/
bash ai_dev_flow/10_TSPEC/scripts/validate_all_tspec.sh docs/10_TSPEC/

Type-specific validation

各类型专属验证

python ai_dev_flow/10_TSPEC/scripts/validate_utest.py docs/10_TSPEC/UTEST/.md python ai_dev_flow/10_TSPEC/scripts/validate_itest.py docs/10_TSPEC/ITEST/.md python ai_dev_flow/10_TSPEC/scripts/validate_stest.py docs/10_TSPEC/STEST/.md python ai_dev_flow/10_TSPEC/scripts/validate_ftest.py docs/10_TSPEC/FTEST/.md
python ai_dev_flow/10_TSPEC/scripts/validate_utest.py docs/10_TSPEC/UTEST/.md python ai_dev_flow/10_TSPEC/scripts/validate_itest.py docs/10_TSPEC/ITEST/.md python ai_dev_flow/10_TSPEC/scripts/validate_stest.py docs/10_TSPEC/STEST/.md python ai_dev_flow/10_TSPEC/scripts/validate_ftest.py docs/10_TSPEC/FTEST/.md

Cross-document validation

跨文档验证

python ai_dev_flow/scripts/validate_cross_document.py --document docs/10_TSPEC/UTEST/UTEST-01_*.md
undefined
python ai_dev_flow/scripts/validate_cross_document.py --document docs/10_TSPEC/UTEST/UTEST-01_*.md
undefined

Manual Checklist

手动检查清单

  • Document Control section at top
  • Test Scope defines component and categories
  • Test Case Index lists all tests with priority
  • Each test case has TSPEC.NN.TT.SS ID
  • Element type code matches document type (40/41/42/43)
  • I/O tables present for all test cases
  • Pseudocode provided for complex logic
  • Error cases documented
  • Coverage Matrix complete
  • TASKS-Ready Score meets type-specific target
  • Cumulative tags: @brd through @spec (8-9 tags)
  • Traceability matrix updated
  • 文档控制章节在顶部
  • 测试范围定义了组件和分类
  • 测试用例索引列出所有测试及其优先级
  • 每个测试用例都有TSPEC.NN.TT.SS ID
  • 元素类型代码与文档类型匹配（40/41/42/43）
  • 所有测试用例都有输入/输出表
  • 复杂逻辑提供了伪代码
  • 错误场景已记录
  • 覆盖矩阵填写完整
  • 任务就绪分数达到各类型专属目标
  • 累计标签：@brd至@spec（8-9个标签）
  • 可追溯性矩阵已更新

Diagram Standards

图表标准

All diagrams MUST use Mermaid syntax. Text-based diagrams (ASCII art, box drawings) are prohibited. See: 
ai_dev_flow/DIAGRAM_STANDARDS.md
and 
mermaid-gen
skill.
所有图表必须使用Mermaid语法。禁止使用基于文本的图表（ASCII艺术、框线图）。 参考: 
ai_dev_flow/DIAGRAM_STANDARDS.md
和
mermaid-gen
技能。

Common Pitfalls

常见陷阱

  1. Wrong element type code: Use 40 for UTEST, 41 for ITEST, 42 for STEST, 43 for FTEST
  2. Missing I/O tables: Every test case needs input/output specification
  3. No coverage matrix: Must track REQ element coverage
  4. Wrong tag format: Use TSPEC.NN.TT.SS for elements, TYPE-NN for documents
  5. Missing cumulative tags: Layer 10 requires all 8-9 upstream tags
  6. Legacy test IDs: Use TSPEC.NN.TT.SS, NOT TC-XXX, UT-XXX, etc.
  7. No pseudocode: Complex tests require algorithm specification
  8. Incomplete error cases: Document expected behavior for all error conditions
  1. 错误的元素类型代码: UTEST用40，ITEST用41，STEST用42，FTEST用43
  2. 缺失输入/输出表: 每个测试用例都需要输入/输出规范
  3. 没有覆盖矩阵: 必须追踪REQ元素的覆盖情况
  4. 错误的标签格式: 元素用TSPEC.NN.TT.SS，文档用TYPE-NN
  5. 缺失累计标签: 第10层需要所有8-9个上游标签
  6. 旧测试ID: 使用TSPEC.NN.TT.SS，不要用TC-XXX、UT-XXX等
  7. 没有伪代码: 复杂测试需要算法规范
  8. 错误场景不完整: 记录所有错误条件下的预期行为

Post-Creation Validation (MANDATORY - NO CONFIRMATION)

创建后验证（强制 - 无需确认）

CRITICAL: Execute this validation loop IMMEDIATELY after document creation. Do NOT proceed to next document until validation passes.
关键: 文档创建后立即执行此验证循环。在验证通过前，不要继续创建下一个文档。

Automatic Validation Loop

自动验证循环

LOOP:
  1. Run: python ai_dev_flow/scripts/validate_cross_document.py --document {doc_path} --auto-fix
  2. IF errors fixed: GOTO LOOP (re-validate)
  3. IF warnings fixed: GOTO LOOP (re-validate)
  4. IF unfixable issues: Log for manual review, continue
  5. IF clean: Mark VALIDATED, proceed
LOOP:
  1. 运行: python ai_dev_flow/scripts/validate_cross_document.py --document {doc_path} --auto-fix
  2. 如果错误已修复: 回到LOOP（重新验证）
  3. 如果警告已修复: 回到LOOP（重新验证）
  4. 如果存在无法修复的问题: 记录以便手动评审，继续
  5. 如果验证通过: 标记为已验证，继续

Validation Command

验证命令

bash
undefined
bash
undefined

Per-document validation (Phase 1)

单文档验证（阶段1）

python ai_dev_flow/scripts/validate_cross_document.py --document docs/10_TSPEC/UTEST/UTEST-NN_slug.md --auto-fix
python ai_dev_flow/scripts/validate_cross_document.py --document docs/10_TSPEC/UTEST/UTEST-NN_slug.md --auto-fix

Layer validation (Phase 2) - run when all TSPEC documents complete

层级验证（阶段2）- 所有TSPEC文档完成后运行

python ai_dev_flow/scripts/validate_cross_document.py --layer TSPEC --auto-fix
undefined
python ai_dev_flow/scripts/validate_cross_document.py --layer TSPEC --auto-fix
undefined

Layer-Specific Upstream Requirements

层级专属上游要求

This LayerRequired Upstream TagsCount
TSPEC (Layer 10)@brd, @prd, @ears, @bdd, @adr, @sys, @req, @spec (+ @ctr if created)8-9 tags
当前层级必填上游标签数量
TSPEC（第10层）@brd, @prd, @ears, @bdd, @adr, @sys, @req, @spec（如果已创建CTR则加@ctr）8-9个标签

Auto-Fix Actions (No Confirmation Required)

自动修复操作（无需确认）

IssueFix Action
Missing upstream tagAdd with upstream document reference
Invalid tag formatCorrect to TYPE.NN.TT.SS (4-segment) or TYPE-NN format
Broken linkRecalculate path from current location
Missing traceability sectionInsert from template
问题修复操作
缺失上游标签添加上游文档引用
无效标签格式修正为TYPE.NN.TT.SS（4段）或TYPE-NN格式
链接断裂从当前位置重新计算路径
缺失可追溯性章节从模板插入

Validation Codes Reference

验证代码参考

CodeDescriptionSeverity
XDOC-001Referenced requirement ID not foundERROR
XDOC-002Missing cumulative tagERROR
XDOC-003Upstream document not foundERROR
XDOC-006Tag format invalidERROR
XDOC-007Gap in cumulative tag chainERROR
XDOC-009Missing traceability sectionERROR
代码描述严重程度
XDOC-001引用的需求ID未找到错误
XDOC-002缺失累计标签错误
XDOC-003上游文档未找到错误
XDOC-006标签格式无效错误
XDOC-007累计标签链存在缺口错误
XDOC-009缺失可追溯性章节错误

Quality Gate

质量门

Blocking: YES - Cannot proceed to next document until Phase 1 validation passes with 0 errors.
阻塞: 是 - 阶段1验证必须零错误通过，才能继续创建下一个文档。

Next Skill

下一个技能

After creating TSPEC, use:
doc-tasks
 - Create Task Breakdown (Layer 11)
The TASKS will:
  • Reference this TSPEC for test implementation
  • Include all 9-10 upstream tags
  • Break SPEC and TSPEC into actionable tasks
  • Provide AI-structured TODO format
创建TSPEC后，使用:
doc-tasks
 - 创建任务分解（第11层）
TASKS将:
  • 引用此TSPEC用于测试实现
  • 包含所有9-10个上游标签
  • 将SPEC和TSPEC分解为可执行任务
  • 提供AI结构化的TODO格式

Reference Documents

参考文档

TSPEC artifacts do not support REF documents. Reference documents are limited to BRD and ADR types only per the SDD framework.
For supplementary documentation needs, create:
  • BRD-REF: Business context documentation
  • ADR-REF: Test strategy guides, coverage analysis reports
TSPEC工件不支持REF文档。根据SDD框架，参考文档仅限于BRD和ADR类型。
如需补充文档，创建:
  • BRD-REF: 业务上下文文档
  • ADR-REF: 测试策略指南、覆盖分析报告

Related Resources

相关资源

  • Templates: 
    • ai_dev_flow/10_TSPEC/UTEST/UTEST-MVP-TEMPLATE.md
    • ai_dev_flow/10_TSPEC/ITEST/ITEST-MVP-TEMPLATE.md
    • ai_dev_flow/10_TSPEC/STEST/STEST-MVP-TEMPLATE.md
    • ai_dev_flow/10_TSPEC/FTEST/FTEST-MVP-TEMPLATE.md
  • TSPEC README: 
    ai_dev_flow/10_TSPEC/README.md
  • TSPEC Index: 
    ai_dev_flow/10_TSPEC/TSPEC-00_index.md
  • Traceability Matrix Template: 
    ai_dev_flow/10_TSPEC/TSPEC-00_TRACEABILITY_MATRIX-TEMPLATE.md
  • Shared Standards: 
    .claude/skills/doc-flow/SHARED_CONTENT.md
  • doc-naming skill: 
    .claude/skills/doc-naming/SKILL.md
    (element type codes)
  • doc-spec skill: 
    .claude/skills/doc-spec/SKILL.md
    (upstream SPEC creation)
  • quality-advisor skill: 
    .claude/skills/quality-advisor/SKILL.md
    (quality guidance)
  • 模板: 
    • ai_dev_flow/10_TSPEC/UTEST/UTEST-MVP-TEMPLATE.md
    • ai_dev_flow/10_TSPEC/ITEST/ITEST-MVP-TEMPLATE.md
    • ai_dev_flow/10_TSPEC/STEST/STEST-MVP-TEMPLATE.md
    • ai_dev_flow/10_TSPEC/FTEST/FTEST-MVP-TEMPLATE.md
  • TSPEC说明文档: 
    ai_dev_flow/10_TSPEC/README.md
  • TSPEC索引: 
    ai_dev_flow/10_TSPEC/TSPEC-00_index.md
  • 可追溯性矩阵模板: 
    ai_dev_flow/10_TSPEC/TSPEC-00_TRACEABILITY_MATRIX-TEMPLATE.md
  • 共享标准: 
    .claude/skills/doc-flow/SHARED_CONTENT.md
  • 文档命名技能: 
    .claude/skills/doc-naming/SKILL.md
    （元素类型代码）
  • 文档-SPEC技能: 
    .claude/skills/doc-spec/SKILL.md
    （上游SPEC创建）
  • 质量顾问技能: 
    .claude/skills/quality-advisor/SKILL.md
    （质量指南）

Quick Reference

快速参考

TSPEC Purpose: Test specifications for TDD workflow
Layer: 10
Element ID Format: 
TSPEC.NN.TT.SS
  • Unit Test = 40
  • Integration Test = 41
  • Smoke Test = 42
  • Functional Test = 43
Removed Patterns: TC-XXX, UT-XXX, IT-XXX, ST-XXX, FT-XXX
Tags Required: @brd through @spec (8-9 tags)
Format: Markdown with I/O tables and pseudocode
TSPEC Types:
  • UTEST: Unit tests (>=90% coverage, REQ-focused)
  • ITEST: Integration tests (>=85% coverage, CTR-focused)
  • STEST: Smoke tests (100% critical paths, <5min execution)
  • FTEST: Functional tests (>=85% SYS coverage)
Key Sections:
  • Document Control
  • Test Scope (component, categories, dependencies)
  • Test Case Index
  • Test Case Details (I/O tables, pseudocode, error cases)
  • Coverage Matrix
  • Traceability (cumulative tags)
Quality Gate: Type-specific TASKS-Ready Score
Next: doc-tasks
TSPEC用途: 为TDD工作流提供测试规范
层级: 10
元素ID格式: 
TSPEC.NN.TT.SS
  • 单元测试 = 40
  • 集成测试 = 41
  • 冒烟测试 = 42
  • 功能测试 = 43
已弃用格式: TC-XXX, UT-XXX, IT-XXX, ST-XXX, FT-XXX
必填标签: @brd至@spec（8-9个标签）
格式: 带输入/输出表和伪代码的Markdown
TSPEC类型:
  • UTEST: 单元测试（>=90%覆盖率，聚焦REQ）
  • ITEST: 集成测试（>=85%覆盖率，聚焦CTR）
  • STEST: 冒烟测试（100%关键路径，执行时间<5分钟）
  • FTEST: 功能测试（>=85% SYS覆盖率）
关键章节:
  • 文档控制
  • 测试范围（组件、分类、依赖关系）
  • 测试用例索引
  • 测试用例详情（输入/输出表、伪代码、错误场景）
  • 覆盖矩阵
  • 可追溯性（累计标签）
质量门: 各类型专属的任务就绪分数
下一步: doc-tasks

Version History

版本历史

VersionDateChanges
1.02026-02-08Initial release with UTEST/ITEST/STEST/FTEST support (codes 40-43)
版本日期变更
1.02026-02-08初始版本，支持UTEST/ITEST/STEST/FTEST（代码40-43）