ai-sdlc-sdd

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ai-sdlc-sdd: Spec Driven Development

ai-sdlc-sdd：规范驱动开发（SDD）

Internal AI SDLC skill, not client-facing by default. Every rule below is important to follow. None of it can be skipped. Before producing the final artifact, confirm required inputs, target audience, missing facts, output format, and constraints when they are unclear. Do not invent missing information. Ask concise clarification questions when required inputs are absent.

内部AI SDLC技能，默认不面向客户。以下每条规则都必须严格遵守，不得跳过任何一条。在生成最终工件前，若对必要输入、目标受众、缺失信息、输出格式或约束条件存在疑问，请先确认清楚。不得编造缺失信息。当必要输入缺失时，请提出简洁的澄清问题。

0. Skill Card

0. 技能卡片

Skill name:
```
ai-sdlc-sdd
```
Primary audience: Dev
Supporting audience: BA, QA, PM
Audience tags: Dev, BA, QA, PM
SDLC stage: Repository SDD workflow
Purpose: Create, update, validate, and enforce the AI SDLC SDD package for medium and large changes before implementation expands.
Output: SDD package, Markdown execution plan, TOON machine plan, validation status, task alignment, and implementation handoff

技能名称：
```
ai-sdlc-sdd
```
主要受众：Dev
支持受众：BA、QA、PM
受众标签：Dev、BA、QA、PM
SDLC阶段：仓库SDD工作流
目的：在实现范围扩大前，创建、更新、验证并强制执行针对中大型变更的AI SDLC SDD包。
输出：SDD包、Markdown执行计划、TOON机器计划、验证状态、任务对齐情况、实现交接文档

0.1 Required Inputs

0.1 必要输入

Medium or large change request.
Affected systems, APIs, packages, or artifacts.
Existing spec folder or proposed feature name if available.

中大型变更请求。
受影响的系统、API、包或工件。
现有规范文件夹（若可用）或提议的功能名称。

0.2 Clarification Rules

0.2 澄清规则

Ask concise questions before finalizing when role, artifact, requirements, scope, audience, or constraints are unclear.
If optional information is missing, mark it as
```
TBD
```
,
```
Not provided
```
, or
```
Assumption
```
instead of inventing it.
Separate confirmed facts from assumptions and open questions.
Do not proceed to downstream synthesis when a required upstream artifact or decision is missing.

当角色、工件、需求、范围、受众或约束条件不明确时，请在最终确定前提出简洁的问题。
若可选信息缺失，请标记为
```
TBD
```
、
```
未提供
```
或
```
假设
```
，不得编造内容。
将已确认事实与假设、未解决问题分开记录。
当必要的上游工件或决策缺失时，不得推进到下游合成环节。

0.2.1 Flow Mode Flags

0.2.1 流程模式标志

Support two explicit execution flags:
```
--quick-flow
```
and
```
--full-flow
```
.
If both flags are supplied,
```
--full-flow
```
takes precedence because it is the stricter mode.
```
--quick-flow
```
: move fast, make high-quality progress with available context, avoid clarification questions unless continuing would create material product, security, compliance, data-loss, or irreversible implementation risk.
In
```
--quick-flow
```
, use documented assumptions, recommended defaults, existing repository patterns, and the nearest available artifact evidence; record important assumptions and decisions in
```
decision-log.md
```
.
In
```
--quick-flow
```
, run only focused checks that are directly relevant, cheap, and likely to catch regressions for the requested work; report any skipped broader checks as residual risk.
```
--full-flow
```
: ask concise clarification questions when inputs, scope, ownership, acceptance criteria, or decisions are unclear; do not silently assume material requirements.
In
```
--full-flow
```
, verify upstream and downstream artifacts, decision-log entries, traceability links, acceptance criteria, and validation evidence before finalizing.
In
```
--full-flow
```
, SDD must consume upstream refinement context from
```
specs-refiniment/<feature-name>/
```
; missing or incomplete delivery-spec or QA-readiness context blocks implementation SDD handoff.
In
```
--full-flow
```
, run or recommend the skill-appropriate gates, reviews, scripts, and validation commands needed for end-to-end confidence; document any blocked verification explicitly.
When neither flag is supplied, follow the skill default rules and choose the least risky behavior for the request size and domain.

支持两种明确的执行标志：
```
--quick-flow
```
和
```
--full-flow
```
。
若同时提供两个标志，
```
--full-flow
```
优先级更高，因为它是更严格的模式。
```
--quick-flow
```
：快速推进，利用现有上下文开展高质量工作；除非继续推进会造成产品、安全、合规、数据丢失或不可逆的实现风险，否则避免提出澄清问题。
在
```
--quick-flow
```
模式下，使用已记录的假设、推荐默认值、现有仓库模式和最接近的可用工件证据；将重要假设和决策记录在
```
decision-log.md
```
中。
在
```
--quick-flow
```
模式下，仅运行与请求工作直接相关、成本低且可能发现回归问题的聚焦检查；将所有跳过的更广泛检查报告为残留风险。
```
--full-flow
```
：当输入、范围、所有权、验收标准或决策不明确时，提出简洁的澄清问题；不得默认假设关键需求。
在
```
--full-flow
```
模式下，在最终确定前验证上游和下游工件、决策日志条目、可追溯性链接、验收标准和验证证据。
在
```
--full-flow
```
模式下，SDD必须从
```
specs-refiniment/<feature-name>/
```
中获取上游细化上下文；若交付规范或QA就绪上下文缺失或不完整，将阻止实现SDD交接。
在
```
--full-flow
```
模式下，运行或推荐所需的技能适配关卡、评审、脚本和验证命令，以确保端到端可信度；明确记录任何被阻止的验证环节。
若未提供任何标志，请遵循技能默认规则，并根据请求规模和领域选择风险最低的行为。

0.3 Output Rules

0.3 输出规则

Keep output structured with headings and bullets.
Make findings, gaps, risks, and blockers explicit.
Tie recommendations to evidence from the provided artifact, repository,
```
specs-refiniment/<feature-name>/<file.md>
```
workspace, or user context.
Include role ownership when the output creates follow-up work for BA, QA, Dev, PM, or Delivery.
Return progress, completion, validation, and handoff summaries directly in the Codex response.

Before the final response, emit the

ai-sdlc-handoff/v1

contract with

result

blockers

next_required

, and

next_optional

; every action includes

reason

command

, and

expected_artifact

Do not create
```
summary.txt
```
,
```
*-summary.txt
```
, or another standalone summary file unless the user explicitly requests one.
Keep durable writes limited to the canonical lifecycle artifacts, decision log, human-readable index, and
```
_ai_sdlc
```
machine files.
Let shared helpers migrate legacy paths on the next write; never overwrite or manually merge divergent legacy and canonical files.

保持输出结构清晰，使用标题和项目符号。
明确指出发现的问题、差距、风险和阻塞点。
建议需与提供的工件、仓库、
```
specs-refiniment/<feature-name>/<file.md>
```
工作区或用户上下文的证据关联。
当输出为BA、QA、Dev、PM或交付团队创建后续工作时，需明确角色归属。
在Codex响应中直接返回进度、完成情况、验证和交接摘要。
在最终响应前，输出包含
```
result
```
、
```
blockers
```
、
```
next_required
```
和
```
next_optional
```
字段的
```
ai-sdlc-handoff/v1
```
契约；每个操作需包含
```
reason
```
、
```
command
```
和
```
expected_artifact
```
字段。
除非用户明确要求，否则不得创建
```
summary.txt
```
、
```
*-summary.txt
```
或其他独立摘要文件。
仅将持久化写入限制在标准生命周期工件、决策日志、人类可读索引和
```
_ai_sdlc
```
机器文件中。
让共享助手在下次写入时迁移旧路径；不得覆盖或手动合并不一致的旧文件和标准文件。

0.4 Artifact Routing

0.4 工件路由

Maintain a feature decision log whenever this skill records, resolves, changes, or depends on a product, delivery, QA, security, validation, branching, implementation, or rollout decision.
For PM, BA, QA, Delivery, discovery, planning, refinement, and readiness work, write decisions to
```
specs-refiniment/<feature-name>/decision-log.md
```
.
For developer implementation SDD work, write decisions to
```
specs/<feature-name>/decision-log.md
```
.
Each decision-log entry must include date, decision, context or evidence, options considered when relevant, owner, status, and links to affected artifacts, tasks, tests, or validation evidence.

Use this exact decision-log structure:

markdown

# Decision Log

| ID | Date | Status | Owner | Decision | Context/Evidence | Options Considered | Affected Artifacts | Validation/Trace Links |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| DEC-001 | YYYY-MM-DD | proposed / accepted / superseded / rejected | role or name | concise decision | source facts, artifact links, or evidence | option A; option B; recommended default | affected docs, tasks, code, tests, or rollout notes | requirement IDs, test IDs, validation commands, PRs, commits, or tickets |

Use
```
specs/
```
only for developer implementation SDD packages and repo-governance artifacts.
Do not place PM, BA, QA, Delivery, discovery, planning, refinement, or readiness outputs in
```
specs/
```
; those belong at
```
specs-refiniment/<feature-name>/<file.md>
```
.
When consuming
```
specs-refiniment/<feature-name>/<file.md>
```
, treat it as upstream refinement context and create or update
```
specs/
```
only when implementation work is explicitly in scope.

每当本技能记录、解决、更改或依赖产品、交付、QA、安全、验证、分支、实现或发布决策时，需维护功能决策日志。
对于PM、BA、QA、交付、探索、规划、细化和就绪工作，将决策写入
```
specs-refiniment/<feature-name>/decision-log.md
```
。
对于开发人员实现SDD的工作，将决策写入
```
specs/<feature-name>/decision-log.md
```
。
每个决策日志条目必须包含日期、决策内容、上下文或证据、相关备选方案（若适用）、负责人、状态以及指向受影响工件、任务、测试或验证证据的链接。

使用以下精确的决策日志结构：

markdown

# Decision Log

| ID | Date | Status | Owner | Decision | Context/Evidence | Options Considered | Affected Artifacts | Validation/Trace Links |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| DEC-001 | YYYY-MM-DD | proposed / accepted / superseded / rejected | role or name | concise decision | source facts, artifact links, or evidence | option A; option B; recommended default | affected docs, tasks, code, tests, or rollout notes | requirement IDs, test IDs, validation commands, PRs, commits, or tickets |

仅将
```
specs/
```
用于开发人员实现的SDD包和仓库治理工件。
不得将PM、BA、QA、交付、探索、规划、细化或就绪输出放入
```
specs/
```
；这些内容应放在
```
specs-refiniment/<feature-name>/<file.md>
```
中。
当使用
```
specs-refiniment/<feature-name>/<file.md>
```
时，将其视为上游细化上下文；仅当实现工作明确在范围内时，才创建或更新
```
specs/
```
中的内容。

0.5 Feature State Machine

0.5 特性状态机

Maintain feature lifecycle state in TOON at

specs-refiniment/<feature-name>/_ai_sdlc/state.toon

for refinement work and

specs/<feature-name>/_ai_sdlc/state.toon

for implementation work.

Before executing this skill for a feature, check the state machine with

python3 skills/_shared/state_machine.py check --feature <feature-name> --skill <this-skill-name> --workspace <refinement|implementation> --quick-flow|--full-flow

When this skill starts durable work, mark it in progress with
```
begin
```
; when the skill's required artifact or review is complete, mark it done with
```
complete
```
and include
```
--artifacts <path>
```
plus
```
--decision-ref DEC-###
```
when a decision was involved.
In
```
--full-flow
```
, do not proceed when predecessor stages are incomplete, another lifecycle skill is active, or the state file reports a blocker.
In
```
--quick-flow
```
, a predecessor skip is allowed only when continuing is low risk and the command includes
```
--assumption "..."
```
or
```
--decision-ref DEC-###
```
; record the same assumption or decision in
```
decision-log.md
```
.

Use

python3 skills/_shared/state_machine.py status --feature <feature-name> --workspace <refinement|implementation> --format toon

to emit compact LLM-readable state before choosing the next skill.

The state machine is feature-scoped: do not reuse a
```
state.toon
```
across unrelated feature folders.

在TOON中维护特性生命周期状态：细化工作的状态存储在
```
specs-refiniment/<feature-name>/_ai_sdlc/state.toon
```
，实现工作的状态存储在
```
specs/<feature-name>/_ai_sdlc/state.toon
```
。

在为某个特性执行本技能前，使用以下命令检查状态机：

python3 skills/_shared/state_machine.py check --feature <feature-name> --skill <this-skill-name> --workspace <refinement|implementation> --quick-flow|--full-flow

。

当本技能开始持久化工作时，用
```
begin
```
标记为进行中；当技能所需的工件或评审完成时，用
```
complete
```
标记为已完成，若涉及决策，需添加
```
--artifacts <path>
```
和
```
--decision-ref DEC-###
```
。
在
```
--full-flow
```
模式下，当前置阶段未完成、另一个生命周期技能正在运行或状态文件报告阻塞时，不得推进。
在
```
--quick-flow
```
模式下，仅当继续推进风险较低且命令包含
```
--assumption "..."
```
或
```
--decision-ref DEC-###
```
时，才允许跳过前置阶段；需在
```
decision-log.md
```
中记录相同的假设或决策。

使用以下命令输出紧凑的LLM可读状态，再选择下一个技能：

python3 skills/_shared/state_machine.py status --feature <feature-name> --workspace <refinement|implementation> --format toon

。

状态机按特性划分范围：不得在不相关的特性文件夹之间复用
```
state.toon
```
。

0.6 Artifact Metadata And Metatags

0.6 工件元数据与元标签

Every Markdown artifact generated or updated by this skill must start with an
```
artifact_metadata
```
YAML frontmatter block before the first visible heading.

Use schema

ai-sdlc-artifact-metadata/v1

and keep these fields current:

feature

artifact

path

workspace

skill

flow_mode

state_file

decision_log

status

owner

created_at

updated_at

trace_ids

related_artifacts

validation

, and

metatags

```
metatags
```
must include at minimum
```
ai-sdlc
```
, the workspace (
```
refinement
```
or
```
implementation
```
), this skill name, the artifact type or filename stem, and a lifecycle/status tag such as
```
draft
```
,
```
review
```
,
```
approved
```
, or
```
validated
```
.
When
```
--quick-flow
```
is active, set
```
flow_mode: quick
```
, keep assumptions visible in the body, and add tags for major defaults or unresolved risk only when they help retrieval.
When
```
--full-flow
```
is active, set
```
flow_mode: full
```
, keep blockers and validation evidence reflected in
```
status
```
,
```
validation
```
,
```
trace_ids
```
, and
```
related_artifacts
```
.
Update metadata whenever the artifact path, status, owner, trace links, validation evidence, related artifacts, or decision references change.
Metadata is an index for routing, retrieval, and traceability; it does not replace the artifact body,
```
decision-log.md
```
, or
```
state.toon
```
.

本技能生成或更新的每个Markdown工件，必须在第一个可见标题前包含
```
artifact_metadata
```
YAML前置块。

使用

ai-sdlc-artifact-metadata/v1

schema，并保持以下字段最新：

feature

、

artifact

、

path

、

workspace

、

skill

、

flow_mode

、

state_file

、

decision_log

、

status

、

owner

、

created_at

、

updated_at

、

trace_ids

、

related_artifacts

、

validation

和

metatags

。

```
metatags
```
必须至少包含
```
ai-sdlc
```
、工作区（
```
refinement
```
或
```
implementation
```
）、本技能名称、工件类型或文件名主干，以及生命周期/状态标签（如
```
draft
```
、
```
review
```
、
```
approved
```
或
```
validated
```
）。
当
```
--quick-flow
```
模式激活时，设置
```
flow_mode: quick
```
，在正文中显示假设，仅当有助于检索时才添加主要默认值或未解决风险的标签。
当
```
--full-flow
```
模式激活时，设置
```
flow_mode: full
```
，在
```
status
```
、
```
validation
```
、
```
trace_ids
```
和
```
related_artifacts
```
中反映阻塞点和验证证据。
当工件路径、状态、负责人、追溯链接、验证证据、相关工件或决策引用发生变化时，更新元数据。
元数据是用于路由、检索和可追溯性的索引；不能替代工件正文、
```
decision-log.md
```
或
```
state.toon
```
。

0.7 Specs Index

0.7 规范索引

Before searching across feature folders, inspect the compact LLM index first:
```
specs-refiniment/_ai_sdlc/specs-index.toon
```
for refinement work or
```
specs/_ai_sdlc/specs-index.toon
```
for implementation work.
Use the human-readable index at
```
specs-refiniment/specs-index.md
```
or
```
specs/specs-index.md
```
when reporting feature coverage, artifact inventory, or handoff status to people.

After this skill creates or materially updates an artifact, refresh the matching workspace index with

python3 skills/_shared/ai_sdlc_specs_index.py --workspace <refinement|implementation> --quick-flow|--full-flow

In
```
--quick-flow
```
, rely on
```
specs-index.toon
```
to choose the smallest relevant artifact set before opening files.
In
```
--full-flow
```
, verify the updated artifact appears in both
```
specs-index.toon
```
and
```
specs-index.md
```
before final handoff.
The specs index summarizes artifact metadata and state; it does not replace reading the selected source artifacts when details, approvals, or validation evidence matter.

在跨特性文件夹搜索前，先查看紧凑的LLM索引：细化工作查看
```
specs-refiniment/_ai_sdlc/specs-index.toon
```
，实现工作查看
```
specs/_ai_sdlc/specs-index.toon
```
。
当向人员报告特性覆盖范围、工件清单或交接状态时，使用人类可读索引
```
specs-refiniment/specs-index.md
```
或
```
specs/specs-index.md
```
。

当本技能创建或大幅更新工件后，使用以下命令刷新对应工作区的索引：

python3 skills/_shared/ai_sdlc_specs_index.py --workspace <refinement|implementation> --quick-flow|--full-flow

。

在
```
--quick-flow
```
模式下，依赖
```
specs-index.toon
```
选择最小的相关工件集，再打开文件。
在
```
--full-flow
```
模式下，在最终交接前验证更新后的工件是否同时出现在
```
specs-index.toon
```
和
```
specs-index.md
```
中。
规范索引汇总工件元数据和状态；当细节、审批或验证证据很重要时，不能替代阅读选定的源工件。

References

参考资料

Use
```
scripts/analyze_spec.py
```
when deterministic validation, planning, or formatting is required by the workflow; pass the same
```
--quick-flow
```
or
```
--full-flow
```
flag that was supplied to the skill when supported.
Use
```
scripts/check_checklist.py
```
when deterministic validation, planning, or formatting is required by the workflow; pass the same
```
--quick-flow
```
or
```
--full-flow
```
flag that was supplied to the skill when supported.
Use
```
scripts/check_clarify.py
```
when deterministic validation, planning, or formatting is required by the workflow; pass the same
```
--quick-flow
```
or
```
--full-flow
```
flag that was supplied to the skill when supported.
Use
```
scripts/resolve_active_spec.py
```
when deterministic validation, planning, or formatting is required by the workflow; pass the same
```
--quick-flow
```
or
```
--full-flow
```
flag that was supplied to the skill when supported.
Use
```
scripts/sdd_status.py
```
when deterministic validation, planning, or formatting is required by the workflow; pass the same
```
--quick-flow
```
or
```
--full-flow
```
flag that was supplied to the skill when supported.
Use
```
scripts/sdd_context.py
```
before broad SDD reads; inspect its exact AC/TC/task/decision anchors and follow only the reported
```
next_reads
```
ranges.
Use
```
scripts/spec_helpers.py
```
when deterministic validation, planning, or formatting is required by the workflow; pass the same
```
--quick-flow
```
or
```
--full-flow
```
flag that was supplied to the skill when supported.
Use
```
scripts/validate_spec.py
```
when deterministic validation, planning, or formatting is required by the workflow; pass the same
```
--quick-flow
```
or
```
--full-flow
```
flag that was supplied to the skill when supported.
Use
```
scripts/plan_links.py
```
to emit, write, or validate the required
```
_ai_sdlc/plan.toon
```
machine plan plus
```
plan.md
```
execution plan and cross-artifact trace map.

Use

scripts/sdd_artifact_scaffold.py

to write

requirements.md

design.md

test-cases.md

qa.md

, and

tasks.md

one stdin section at a time.

Use
```
scripts/check_refinement_context.py
```
in
```
--full-flow
```
before SDD handoff to ensure upstream refinement delivery and QA readiness are complete.

当工作流需要确定性验证、规划或格式化时，使用
```
scripts/analyze_spec.py
```
；若支持，传递与技能相同的
```
--quick-flow
```
或
```
--full-flow
```
标志。
当工作流需要确定性验证、规划或格式化时，使用
```
scripts/check_checklist.py
```
；若支持，传递与技能相同的
```
--quick-flow
```
或
```
--full-flow
```
标志。
当工作流需要确定性验证、规划或格式化时，使用
```
scripts/check_clarify.py
```
；若支持，传递与技能相同的
```
--quick-flow
```
或
```
--full-flow
```
标志。
当工作流需要确定性验证、规划或格式化时，使用
```
scripts/resolve_active_spec.py
```
；若支持，传递与技能相同的
```
--quick-flow
```
或
```
--full-flow
```
标志。
当工作流需要确定性验证、规划或格式化时，使用
```
scripts/sdd_status.py
```
；若支持，传递与技能相同的
```
--quick-flow
```
或
```
--full-flow
```
标志。
在进行广泛的SDD读取前，使用
```
scripts/sdd_context.py
```
；查看其精确的AC/TC/task/decision锚点，仅遵循报告的
```
next_reads
```
范围。
当工作流需要确定性验证、规划或格式化时，使用
```
scripts/spec_helpers.py
```
；若支持，传递与技能相同的
```
--quick-flow
```
或
```
--full-flow
```
标志。
当工作流需要确定性验证、规划或格式化时，使用
```
scripts/validate_spec.py
```
；若支持，传递与技能相同的
```
--quick-flow
```
或
```
--full-flow
```
标志。
使用
```
scripts/plan_links.py
```
输出、写入或验证所需的
```
_ai_sdlc/plan.toon
```
机器计划，以及
```
plan.md
```
执行计划和跨工件追溯图。

使用

scripts/sdd_artifact_scaffold.py

分批次写入

requirements.md

、

design.md

、

test-cases.md

、

qa.md

和

tasks.md

，每次从标准输入读取一个章节。

在
```
--full-flow
```
模式下，SDD交接前使用
```
scripts/check_refinement_context.py
```
确保上游细化交付和QA就绪工作已完成。

Script Usage

脚本使用

Use SDD scripts as ordered gates for implementation work; pass the same flow flag supplied to the skill.

Resolve active spec when the target is unclear:

python3 skills/ai-sdlc-sdd/scripts/resolve_active_spec.py --quick-flow --files <changed-file>...

python3 skills/ai-sdlc-sdd/scripts/resolve_active_spec.py --full-flow <spec-or-folder>

Check workflow state for people with

python3 skills/ai-sdlc-sdd/scripts/sdd_status.py --spec specs/<feature-name> --quick-flow

; agents add

--format toon

, and full-flow remains required before handoff.

Build bounded implementation context:

python3 skills/ai-sdlc-sdd/scripts/sdd_context.py specs/<feature-name> --quick-flow

; use

--cache-context

only when cross-session reuse is useful.

Write one artifact section:

python3 skills/ai-sdlc-sdd/scripts/sdd_artifact_scaffold.py specs/<feature-name> --artifact <requirements|design|test-cases|qa|tasks> --section "<section>" --quick-flow

; provide only the section body on stdin.

Repeat section writes and then replace
```
--section ...
```
with
```
--finalize
```
; the AI must not create a temporary content file or directly edit the generated Markdown artifact.
Add a decision with
```
--decision-row
```
and one nine-cell Markdown table row on stdin;
```
--artifact
```
is not required for this action.

Validate structure:

python3 skills/ai-sdlc-sdd/scripts/validate_spec.py specs/<feature-name> --quick-flow

Create or refresh the execution plan pair:

python3 skills/ai-sdlc-sdd/scripts/plan_links.py specs/<feature-name> --write --quick-flow|--full-flow

Emit compact machine plan only:

python3 skills/ai-sdlc-sdd/scripts/plan_links.py specs/<feature-name> --emit-toon --quick-flow|--full-flow

Validate the execution plan links:

python3 skills/ai-sdlc-sdd/scripts/plan_links.py specs/<feature-name> --check --quick-flow|--full-flow

Full-flow upstream gate:

python3 skills/ai-sdlc-sdd/scripts/check_refinement_context.py specs/<feature-name> --full-flow

Full-flow pre-implementation gates, in order:

check_refinement_context.py

check_clarify.py

check_checklist.py

plan_links.py --check

analyze_spec.py

, then

validate_spec.py

, each with

specs/<feature-name> --full-flow

Use quick flow for fast structural confidence; use full flow before expanding implementation tasks, handoff, review, or commit prep.

将SDD脚本作为实现工作的有序关卡；传递与技能相同的流程标志。

当目标不明确时，解析活动规范：

python3 skills/ai-sdlc-sdd/scripts/resolve_active_spec.py --quick-flow --files <changed-file>...

或

python3 skills/ai-sdlc-sdd/scripts/resolve_active_spec.py --full-flow <spec-or-folder>

。

使用以下命令为人员检查工作流状态：
```
python3 skills/ai-sdlc-sdd/scripts/sdd_status.py --spec specs/<feature-name> --quick-flow
```
；代理需添加
```
--format toon
```
，且交接前必须使用全流程模式。

构建有限的实现上下文：

python3 skills/ai-sdlc-sdd/scripts/sdd_context.py specs/<feature-name> --quick-flow

；仅当跨会话复用有用时，使用

--cache-context

。

写入单个工件章节：

python3 skills/ai-sdlc-sdd/scripts/sdd_artifact_scaffold.py specs/<feature-name> --artifact <requirements|design|test-cases|qa|tasks> --section "<section>" --quick-flow

；仅在标准输入中提供章节正文。

重复章节写入后，将
```
--section ...
```
替换为
```
--finalize
```
；AI不得创建临时内容文件或直接编辑生成的Markdown工件。
使用
```
--decision-row
```
添加决策，在标准输入中提供一行九列的Markdown表格；此操作不需要
```
--artifact
```
参数。

验证结构：

python3 skills/ai-sdlc-sdd/scripts/validate_spec.py specs/<feature-name> --quick-flow

。

创建或刷新执行计划对：

python3 skills/ai-sdlc-sdd/scripts/plan_links.py specs/<feature-name> --write --quick-flow|--full-flow

。

仅输出紧凑的机器计划：

python3 skills/ai-sdlc-sdd/scripts/plan_links.py specs/<feature-name> --emit-toon --quick-flow|--full-flow

。

验证执行计划链接：

python3 skills/ai-sdlc-sdd/scripts/plan_links.py specs/<feature-name> --check --quick-flow|--full-flow

。

全流程上游关卡：

python3 skills/ai-sdlc-sdd/scripts/check_refinement_context.py specs/<feature-name> --full-flow

。

全流程实现前关卡，按顺序执行：

check_refinement_context.py

、

check_clarify.py

、

check_checklist.py

、

plan_links.py --check

、

analyze_spec.py

，然后是

validate_spec.py

，每个命令都需添加

specs/<feature-name> --full-flow

。

使用快速流程获取快速的结构可信度；在扩大实现任务、交接、评审或提交准备前，使用全流程模式。

Purpose

目的

Create, update, validate, and enforce the AI SDLC SDD package for medium and large changes before implementation expands.

在实现范围扩大前，创建、更新、验证并强制执行针对中大型变更的AI SDLC SDD包。

Inputs

输入

Read
```
AGENTS.md
```
for change classification and repository workflow rules.
Collect the user request, affected systems, and likely spec name.
Search existing
```
specs/
```
folders for a matching active or historical spec.
Use
```
$ai-sdlc-ba
```
,
```
$ai-sdlc-test-cases
```
, and
```
$ai-sdlc-qa
```
when those phases are incomplete.

--full-flow

, read

specs-refiniment/_ai_sdlc/specs-index.toon

, upstream

state.toon

delivery-spec.md

qa-readiness.md

, and

decision-log.md

before finalizing implementation SDD.

Read existing code only after the spec intent and affected surface are clear enough to avoid scope drift.

阅读
```
AGENTS.md
```
了解变更分类和仓库工作流规则。
收集用户请求、受影响系统和可能的规范名称。
在现有
```
specs/
```
文件夹中搜索匹配的活动或历史规范。
当相关阶段未完成时，使用
```
$ai-sdlc-ba
```
、
```
$ai-sdlc-test-cases
```
和
```
$ai-sdlc-qa
```
。

在

--full-flow

模式下，在最终确定实现SDD前，读取

specs-refiniment/_ai_sdlc/specs-index.toon

、上游

state.toon

、

delivery-spec.md

、

qa-readiness.md

和

decision-log.md

。

仅当规范意图和受影响范围足够明确以避免范围漂移时，才读取现有代码。

Steps

步骤

Classify the change as small, medium, or large using
```
AGENTS.md
```
.
Use the small-change path only for typo fixes, tiny bug fixes, test-only fixes, log text changes, or other no-contract changes.
For medium or large work, find a matching
```
specs/NNN-short-name/
```
folder or create the next numbered folder.
Treat the full folder name as the canonical delivery ID; do not rely on the numeric prefix alone.
Add or update
```
specs/spec-registry.md
```
for tracked governance or delivery-critical work.

Ensure these files exist before implementation:

```
requirements.md
```
```
design.md
```
```
test-cases.md
```
```
qa.md
```
```
tasks.md
```
```
_ai_sdlc/plan.toon
```
```
plan.md
```

Write requirements before design; write design before implementation tasks.

Run the clarify gate after requirements are current:

bash

python3 skills/ai-sdlc-sdd/scripts/check_clarify.py specs/NNN-feature-name

Record implementation traceability, source artifact links, or documented no-ticket exceptions in
```
requirements.md
```
.
Derive test cases before writing tests.
Derive QA acceptance and regression scope before final validation.
Write task entries with explicit
```
Output:
```
and
```
Refs:
```
metadata for new or updated active specs.
Write
```
_ai_sdlc/plan.toon
```
as the required compact machine plan linking SDD artifacts, AC IDs, TC IDs, task IDs, dependencies, decisions, task status, and validation order.
Write
```
plan.md
```
as the required human-readable execution plan and cross-artifact trace map generated from the same links; when
```
_ai_sdlc/plan.toon
```
marks a task
```
done
```
,
```
closed
```
,
```
complete
```
,
```
completed
```
, or
```
validated
```
, mark that task closed in
```
plan.md
```
.
Run the checklist gate before implementation tasks expand:

bash

python3 skills/ai-sdlc-sdd/scripts/check_checklist.py specs/NNN-feature-name

Implement only tasks described in
```
tasks.md
```
and sequenced in
```
_ai_sdlc/plan.toon
```
/
```
plan.md
```
.
Mark task status complete in
```
_ai_sdlc/plan.toon
```
and task checkboxes complete only after code, docs, or validation actually satisfy the task; then refresh
```
plan.md
```
.
Run the analyze gate before implementation handoff or commit prep:

bash

python3 skills/ai-sdlc-sdd/scripts/analyze_spec.py specs/NNN-feature-name

Validate the active spec:

bash

python3 skills/ai-sdlc-sdd/scripts/validate_spec.py specs/NNN-feature-name

Use workflow-state status when the next phase is unclear:

bash

python3 skills/ai-sdlc-sdd/scripts/sdd_status.py --spec specs/NNN-feature-name

Report compliance, completed tasks, validation, and open risks.

使用
```
AGENTS.md
```
将变更分类为小型、中型或大型。
小型变更路径仅适用于拼写错误修复、微小bug修复、仅测试代码修复、日志文本更改或其他无契约变更。
对于中型或大型工作，找到匹配的
```
specs/NNN-short-name/
```
文件夹，或创建下一个编号的文件夹。
将完整文件夹名称视为标准交付ID；不得仅依赖数字前缀。
对于受跟踪的治理或关键交付工作，添加或更新
```
specs/spec-registry.md
```
。

在实现前确保以下文件存在：

```
requirements.md
```
```
design.md
```
```
test-cases.md
```
```
qa.md
```
```
tasks.md
```
```
_ai_sdlc/plan.toon
```
```
plan.md
```

先编写需求，再编写设计；先编写设计，再编写实现任务。

需求更新后，运行澄清关卡：

bash

python3 skills/ai-sdlc-sdd/scripts/check_clarify.py specs/NNN-feature-name

在
```
requirements.md
```
中记录实现可追溯性、源工件链接或已记录的无工单例外情况。
在编写测试前推导测试用例。
在最终验证前推导QA验收和回归范围。
为新的或更新的活动规范编写任务条目，包含明确的
```
Output:
```
和
```
Refs:
```
元数据。
编写
```
_ai_sdlc/plan.toon
```
作为必需的紧凑机器计划，链接SDD工件、AC ID、TC ID、任务ID、依赖项、决策、任务状态和验证顺序。
编写
```
plan.md
```
作为必需的人类可读执行计划和跨工件追溯图，基于相同链接生成；当
```
_ai_sdlc/plan.toon
```
将任务标记为
```
done
```
、
```
closed
```
、
```
complete
```
、
```
completed
```
或
```
validated
```
时，在
```
plan.md
```
中标记该任务为已关闭。
在实现任务扩大前，运行检查清单关卡：

bash

python3 skills/ai-sdlc-sdd/scripts/check_checklist.py specs/NNN-feature-name

仅实现
```
tasks.md
```
中描述且在
```
_ai_sdlc/plan.toon
```
/
```
plan.md
```
中排序的任务。
仅当代码、文档或验证实际满足任务要求时，在
```
_ai_sdlc/plan.toon
```
中标记任务状态为已完成，并勾选任务复选框；然后刷新
```
plan.md
```
。
在实现交接或提交准备前，运行分析关卡：

bash

python3 skills/ai-sdlc-sdd/scripts/analyze_spec.py specs/NNN-feature-name

验证活动规范：

bash

python3 skills/ai-sdlc-sdd/scripts/validate_spec.py specs/NNN-feature-name

当下一阶段不明确时，使用工作流状态命令：

bash

python3 skills/ai-sdlc-sdd/scripts/sdd_status.py --spec specs/NNN-feature-name

报告合规性、已完成任务、验证情况和未解决风险。

Output Spec

输出规范

Use this completion report:

text

SDD compliance:
- Spec: specs/NNN-feature-name
- Change size: small | medium | large
- Requirements: updated | unchanged with reason
- Design: updated | unchanged with reason
- Test cases: updated | unchanged with reason
- QA: updated | unchanged with reason
- Tasks: completed task numbers and remaining task numbers
- Plan: `_ai_sdlc/plan.toon` and `plan.md` updated | unchanged with reason
- Validation: command -> outcome
- Scope control: no drift | drift and spec update
- Residual risk: none | concrete issue

Quality gate:

Pass when the SDD package exists, required sections are populated,
```
_ai_sdlc/plan.toon
```
links AC/TC/TASK/DEC status and dependencies,
```
plan.md
```
reflects those links for humans, tasks match implementation, and the validator passes.
Fail when code starts before missing spec artifacts are created, when implementation exceeds
```
tasks.md
```
, when the clarify/checklist/analyze gates fail, or when task checkboxes are marked complete without evidence.

使用以下完成报告：

text

SDD合规性:
- 规范: specs/NNN-feature-name
- 变更规模: small | medium | large
- 需求: updated | unchanged with reason
- 设计: updated | unchanged with reason
- 测试用例: updated | unchanged with reason
- QA: updated | unchanged with reason
- 任务: 已完成任务编号和剩余任务编号
- 计划: `_ai_sdlc/plan.toon`和`plan.md` updated | unchanged with reason
- 验证: 命令 -> 结果
- 范围控制: 无漂移 | 存在漂移已更新规范
- 残留风险: none | 具体问题

质量关卡:

通过条件：SDD包存在、必需章节已填充、
```
_ai_sdlc/plan.toon
```
关联AC/TC/TASK/DEC状态和依赖项、
```
plan.md
```
为人类展示这些链接、任务与实现匹配、验证器通过。
失败条件：在缺失规范工件创建前开始编写代码、实现超出
```
tasks.md
```
范围、澄清/检查清单/分析关卡失败、无证据标记任务复选框为已完成。

Examples

示例

Spec folder shape:

text

specs/177-skill-instruction-upgrade/
  requirements.md
  design.md
  test-cases.md
  qa.md
  tasks.md
  _ai_sdlc/plan.toon
  plan.md

Completion report sample:

text

SDD compliance:
- Spec: specs/177-skill-instruction-upgrade
- Change size: medium
- Requirements: updated
- Design: updated
- Test cases: updated
- QA: updated
- Tasks: 1-10 completed
- Plan: _ai_sdlc/plan.toon and plan.md updated
- Validation: python3 skills/ai-sdlc-sdd/scripts/validate_spec.py specs/177-skill-instruction-upgrade -> passed
- Scope control: no drift
- Residual risk: none

Invalid counter-example:

text

Implemented feature; will write spec later.

Reject this for medium and large work because the spec is the source of truth.

规范文件夹结构:

text

specs/177-skill-instruction-upgrade/
  requirements.md
  design.md
  test-cases.md
  qa.md
  tasks.md
  _ai_sdlc/plan.toon
  plan.md

完成报告示例:

text

SDD合规性:
- 规范: specs/177-skill-instruction-upgrade
- 变更规模: medium
- 需求: updated
- 设计: updated
- 测试用例: updated
- QA: updated
- 任务: 1-10已完成
- 计划: _ai_sdlc/plan.toon和plan.md updated
- 验证: python3 skills/ai-sdlc-sdd/scripts/validate_spec.py specs/177-skill-instruction-upgrade -> passed
- 范围控制: 无漂移
- 残留风险: none

无效反例:

text

已实现功能；稍后编写规范。

对于中型和大型工作，需拒绝此类情况，因为规范是事实来源。

Edge Cases

边缘情况

Reuse an existing active spec when its requirements clearly match the user request.
Create a new spec when an existing completed or archived spec is only historically related.
Add
```
TODO(dm): exact question
```
when a required decision cannot be discovered and guessing would affect scope, contract, security, or rollout.

Use

Assumptions

Open Questions

, and

Decision Status

sections in

requirements.md

for clarify-gate evidence.

Update the spec first when code and spec conflict during an active change.
Treat unlisted historical numbered specs as
```
unclassified
```
until
```
specs/spec-registry.md
```
says otherwise.
Do not treat scaffolded historical
```
qa.md
```
or
```
test-cases.md
```
files with unresolved TODOs as validated evidence.
Treat missing
```
_ai_sdlc/plan.toon
```
or
```
plan.md
```
as a structural SDD failure, even in quick flow.

When

_ai_sdlc/plan.toon

and

plan.md

disagree, trust

_ai_sdlc/plan.toon

for machine task status and regenerate

plan.md

with

plan_links.py --write

In full flow, treat missing upstream refinement delivery or QA readiness as a blocker unless the predecessor is explicitly skipped with a decision reference.

当现有活动规范的需求与用户请求明确匹配时，复用该规范。
当现有已完成或归档的规范仅与历史相关时，创建新规范。
当无法发现必需的决策且猜测会影响范围、契约、安全或发布时，添加
```
TODO(dm): exact question
```
。

在

requirements.md

中使用

Assumptions

、

Open Questions

和

Decision Status

章节记录澄清关卡的证据。

在活动变更期间，当代码与规范冲突时，先更新规范。
将未列出的历史编号规范视为
```
unclassified
```
，直到
```
specs/spec-registry.md
```
另有说明。
不得将带有未解决TODO的脚手架式历史
```
qa.md
```
或
```
test-cases.md
```
文件视为已验证证据。
即使在快速流程模式下，缺失
```
_ai_sdlc/plan.toon
```
或
```
plan.md
```
也视为SDD结构失败。
当
```
_ai_sdlc/plan.toon
```
与
```
plan.md
```
不一致时，信任
```
_ai_sdlc/plan.toon
```
的机器任务状态，并使用
```
plan_links.py --write
```
重新生成
```
plan.md
```
。
在全流程模式下，除非通过决策引用明确跳过前置环节，否则将上游细化交付或QA就绪工作缺失视为阻塞点。

Scope Boundary

范围边界

Do not replace BA, test-case, QA, review, security, validation, or commit-prep skills; route to them when their phase is needed.
Do not implement major features without requirements, design, test cases, QA, tasks, and plan.
Do not run broad validation by default; use
```
$ai-sdlc-validation
```
for command selection.

不得替代BA、测试用例、QA、评审、安全、验证或提交准备技能；当需要对应阶段时，将工作路由给这些技能。
不得在无需求、设计、测试用例、QA、任务和计划的情况下实现大型功能。
默认不得运行广泛的验证；使用
```
$ai-sdlc-validation
```
选择命令。