Back to Details

spec-architect

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Spec Architect

Spec Architect

Purpose

目的

Use this skill to design high-level functional and technical specifications before implementation. The agent acts as a specification architect who turns product intent, system goals, or rough requirements into structured architecture-ready specs with modules, contracts, boundaries, constraints, and verification criteria.
This skill is domain-generic. It must work for any software system, platform, agent workflow, or integration landscape without embedding project-specific assumptions.
使用本skill在实施前设计高层级的功能与技术规格说明书。Agent将担任规格架构师，把产品意图、系统目标或粗略需求转化为结构化的、可用于架构设计的规格文档，包含模块、契约、边界、约束条件和验证标准。
本skill是领域通用的。它必须适用于任何软件系统、平台、Agent工作流或集成场景，且不包含特定项目的假设。

When to Use

使用场景

Use this skill when the user asks to:
  • Design a high-level technical or functional specification.
  • Turn a PRD, PRP, idea, or rough requirement into an architecture-ready spec.
  • Define modules, boundaries, responsibilities, contracts, and integration points.
  • Separate concerns across functional, application, data, integration, and operational layers.
  • Model an architecture for complex systems before implementation begins.
  • Prepare a spec for spec-driven development or agent-oriented implementation.
  • Clarify what a system must do, must not do, and how success will be verified.
Do not use this skill for low-level coding tasks, detailed backlog tickets, enterprise architecture governance, or product strategy. Keep the output at system/spec architecture level.
当用户提出以下需求时使用本skill：
  • 设计高层级的技术或功能规格说明书。
  • 将PRD、PRP、想法或粗略需求转化为可用于架构设计的规格文档。
  • 定义模块、边界、职责、契约和集成点。
  • 在功能层、应用层、数据层、集成层和操作层之间分离关注点。
  • 在实施开始前为复杂系统建模架构。
  • 为规格驱动开发或面向Agent的实施准备规格文档。
  • 明确系统必须做什么、不能做什么，以及如何验证成功。
请勿将本skill用于低级别编码任务、详细的待办事项工单、企业架构治理或产品战略。输出内容需保持在系统/规格架构层面。

Core Operating Rules

核心操作规则

  1. Design the spec, not the implementation. Define structure, behavior, contracts, boundaries, and constraints. Do not write source code.
  2. Separate functional intent from technical approach. State user-visible behavior first, then technical architecture decisions and constraints.
  3. Define explicit boundaries. Every module, service, agent, data flow, and external dependency must have clear responsibilities and out-of-scope items.
  4. Make contracts concrete. Interfaces must specify inputs, outputs, preconditions, postconditions, errors, ownership, and compatibility expectations.
  5. Preserve traceability. Requirements must map to modules, contracts, constraints, risks, and verification methods.
  6. Model baseline only when relevant. If existing behavior matters, document current assumptions before proposing the target spec architecture.
  7. Avoid unnecessary technology names. Use generic capability terms unless the user provides a technology as a constraint.
  8. Optimize for agent execution. The spec must reduce ambiguity for downstream coding agents by stating allowed changes, forbidden changes, validation rules, and open questions.
  9. Ask only architectural blockers. Ask for missing information only when it affects scope, module boundaries, contracts, risk, data ownership, or verification.
  1. 设计规格，而非实现方案：定义结构、行为、契约、边界和约束条件。不要编写源代码。
  2. 区分功能意图与技术方案：先说明用户可见的行为，再阐述技术架构决策和约束条件。
  3. 定义明确的边界：每个模块、服务、Agent、数据流和外部依赖项都必须有清晰的职责和范围外事项。
  4. 使契约具体化：接口必须指定输入、输出、前置条件、后置条件、错误、所有者和兼容性预期。
  5. 保持可追溯性：需求必须映射到模块、契约、约束条件、风险和验证方法。
  6. 仅在相关时建模基线：如果现有行为重要，在提出目标规格架构之前记录当前假设。
  7. 避免不必要的技术名称：除非用户将技术作为约束条件提供，否则使用通用能力术语。
  8. 针对Agent执行优化：规格文档必须通过说明允许的变更、禁止的变更、验证规则和未解决问题，减少下游编码Agent的歧义。
  9. 仅询问架构障碍：仅当缺失信息影响范围、模块边界、契约、风险、数据所有权或验证时，才询问缺失信息。

Mental Model

思维模型

Think of the specification as an executable contract between product intent and implementation. A strong spec answers:
  • What outcome is required?
  • What is explicitly in and out of scope?
  • Which modules or actors are responsible for each behavior?
  • What contracts connect those modules?
  • What data enters, changes, persists, or leaves the system?
  • What constraints limit implementation choices?
  • What failure modes must be handled?
  • How will the result be verified?
将规格视为产品意图与实现之间的可执行契约。一份完善的规格文档应回答：
  • 需要达成什么结果？
  • 明确包含和排除的范围是什么？
  • 每个行为由哪些模块或角色负责？
  • 哪些契约连接这些模块？
  • 哪些数据进入、变更、持久化或离开系统？
  • 哪些约束条件限制了实现选择？
  • 必须处理哪些故障模式？
  • 如何验证结果？

Specification Architecture Layers

规格架构层

Structure the work across these layers:
LayerRequired Focus
Functional LayerUser-visible capabilities, workflows, rules, permissions, states, and expected outcomes.
Module LayerComponents, services, agents, jobs, adapters, responsibilities, ownership, and boundaries.
Contract LayerInterfaces, events, commands, schemas, inputs, outputs, errors, invariants, and versioning expectations.
Data LayerEntities, lifecycle, ownership, validation, retention, privacy, consistency, and flow between modules.
Integration LayerExternal systems, dependency assumptions, protocols at capability level, failure handling, and fallback behavior.
Operational LayerObservability, performance, reliability, security, scalability, deployment constraints, and supportability.
Verification LayerTest strategy, acceptance checks, conformance criteria, fixtures, mocks, and measurable completion signals.
按以下层级组织工作：
层级重点关注内容
功能层用户可见的能力、工作流、规则、权限、状态和预期结果。
模块层组件、服务、Agent、任务、适配器、职责、所有者和边界。
契约层接口、事件、命令、模式、输入、输出、错误、不变量和版本预期。
数据层实体、生命周期、所有权、验证、保留、隐私、一致性以及模块间的数据流。
集成层外部系统、依赖假设、能力级别的协议、故障处理和回退行为。
操作层可观测性、性能、可靠性、安全性、可扩展性、部署约束和可支持性。
验证层测试策略、验收检查、一致性标准、固定装置、模拟对象和可衡量的完成信号。

Execution Workflow

执行工作流

Phase 1: Intake and Scope Framing

阶段1：需求收集与范围界定

  1. Identify the objective, actors, primary workflows, constraints, and non-goals.
  2. Determine whether the user supplied product requirements, existing behavior, or target-state intent.
  3. Capture assumptions and unknowns.
  4. Ask focused questions only for missing information that changes the architecture.
  1. 确定目标、角色、主要工作流、约束条件和非目标。
  2. 判断用户提供的是产品需求、现有行为还是目标状态意图。
  3. 记录假设和未知事项。
  4. 仅当缺失信息会改变架构时，提出针对性问题。

Phase 2: Functional Architecture

阶段2：功能架构

  1. Define core capabilities and user-visible workflows.
  2. Identify domain rules, states, permissions, and error conditions.
  3. Separate mandatory behavior from optional or future behavior.
  4. Map each functional requirement to an owner module or actor.
  1. 定义核心能力和用户可见的工作流。
  2. 识别领域规则、状态、权限和错误条件。
  3. 区分强制行为与可选或未来行为。
  4. 将每个功能需求映射到所属模块或角色。

Phase 3: Technical Architecture

阶段3：技术架构

  1. Propose modules with single, clear responsibilities.
  2. Define contracts between modules.
  3. Model data ownership and data movement.
  4. Identify integration boundaries and dependency risks.
  5. Document non-functional constraints and tradeoffs.
  1. 提出具有单一明确职责的模块。
  2. 定义模块间的契约。
  3. 建模数据所有权和数据流转。
  4. 识别集成边界和依赖风险。
  5. 记录非功能约束条件和权衡。

Phase 4: Agent-Oriented Readiness

阶段4：面向Agent的就绪准备

  1. Add implementation guardrails for downstream agents.
  2. Define files, modules, or areas likely to change only if known from context.
  3. State what agents may change, must ask before changing, and must not change.
  4. Add verification criteria and expected evidence.
  1. 为下游Agent添加实施准则。
  2. 定义可能仅在上下文已知时变更的文件、模块或区域。
  3. 说明Agent可以变更的内容、变更前必须询问的内容以及禁止变更的内容。
  4. 添加验证标准和预期证据。

Required Output Structure

要求的输出结构

Use this structure unless the user asks for a narrower deliverable:
markdown
undefined
除非用户要求更窄范围的交付物，否则使用以下结构：
markdown
undefined

<Specification Architecture Title>

<Specification Architecture Title>

1. Executive Summary

1. 执行摘要

  • Objective:
  • Scope:
  • Primary actors:
  • Target outcome:
  • Key constraints:
  • 目标:
  • 范围:
  • 主要角色:
  • 目标结果:
  • 关键约束:

2. Context and Assumptions

2. 上下文与假设

  • Current context or baseline:
  • Assumptions:
  • Open questions:
  • Non-goals:
  • 当前上下文或基线:
  • 假设:
  • 未解决问题:
  • 非目标:

3. Functional Specification

3. 功能规格

IDCapabilityActorBehaviorBusiness/User ValuePriority
ID能力角色行为业务/用户价值优先级

4. System Boundaries

4. 系统边界

In Scope

包含范围

  • <Included behavior or responsibility>
  • <Included behavior or responsibility>

Out of Scope

排除范围

  • <Excluded behavior or responsibility>
  • <Excluded behavior or responsibility>

Ask Before Changing

变更前需询问

  • <Sensitive area or decision>
  • <Sensitive area or decision>

5. Module and Responsibility Model

5. 模块与职责模型

ModuleResponsibilityOwnsDoes Not OwnDepends On
模块职责拥有不拥有依赖

6. Contracts and Interfaces

6. 契约与接口

ContractProducerConsumerInputOutputErrorsInvariants
契约生产者消费者输入输出错误不变量

7. Data Model and Flow

7. 数据模型与流转

  • Core entities:
  • Data ownership:
  • Data lifecycle:
  • Validation rules:
  • Data flow summary:
  • 核心实体:
  • 数据所有权:
  • 数据生命周期:
  • 验证规则:
  • 数据流摘要:

8. Failure Modes and Edge Cases

8. 故障模式与边缘情况

ScenarioTriggerExpected BehaviorOwnerVerification
场景触发条件预期行为所有者验证

9. Non-Functional Requirements

9. 非功能需求

CategoryRequirementConstraintValidation Method
类别需求约束验证方法

10. Architecture Decisions

10. 架构决策

DecisionRationaleAlternativesTradeoffsReversibility
决策理由替代方案权衡可逆性

11. Agent Implementation Guardrails

11. Agent实施准则

Always Allowed

始终允许

  • <Safe change>
  • <Safe change>

Ask Before

变更前需询问

  • <Change requiring confirmation>
  • <Change requiring confirmation>

Never Do

禁止操作

  • <Forbidden change>
  • <Forbidden change>

12. Verification Plan

12. 验证计划

  • Unit-level checks:
  • Integration checks:
  • Contract checks:
  • Manual checks:
  • Observability or operational checks:
  • 单元级检查:
  • 集成检查:
  • 契约检查:
  • 手动检查:
  • 可观测性或操作检查:

13. Traceability Matrix

13. 追溯矩阵

RequirementModuleContractData ImpactVerification
undefined
需求模块契约数据影响验证
undefined

Module Boundary Rules

模块边界规则

  • Each module must have one primary reason to change.
  • A module must own its data or explicitly depend on another owner.
  • A module must expose behavior through a documented contract, not hidden coupling.
  • Cross-module interactions must define success, failure, and retry or fallback behavior.
  • Shared concerns must be named as platform, policy, or infrastructure capabilities rather than duplicated across modules.
  • If a boundary is uncertain, document the options and tradeoffs instead of choosing silently.
  • 每个模块必须有一个主要的变更理由。
  • 模块必须拥有其数据，或明确依赖于另一个所有者。
  • 模块必须通过文档化的契约暴露行为，而非隐藏耦合。
  • 跨模块交互必须定义成功、失败以及重试或回退行为。
  • 共享关注点必须命名为平台、策略或基础设施能力，而非在模块间重复。
  • 如果边界不确定，记录选项和权衡，而非默默选择。

Contract Quality Rules

契约质量规则

Every contract must define:
  • Purpose and owner.
  • Producer and consumer.
  • Inputs and validation rules.
  • Outputs and expected states.
  • Error cases and recovery behavior.
  • Idempotency or ordering expectations when relevant.
  • Compatibility or versioning expectations when relevant.
  • Observability signals needed to debug failures.
每个契约必须定义：
  • 目的和所有者。
  • 生产者和消费者。
  • 输入和验证规则。
  • 输出和预期状态。
  • 错误情况和恢复行为。
  • 相关时的幂等性或顺序预期。
  • 相关时的兼容性或版本预期。
  • 调试故障所需的可观测性信号。

Verification Rules

验证规则

  • Every functional requirement must have at least one verification method.
  • Every external dependency must have a failure-mode test or manual validation path.
  • Every contract must be testable with representative valid and invalid inputs.
  • Every non-functional requirement must include a measurable threshold or 
    TBD threshold
    .
  • Every guardrail must be actionable for a downstream implementation agent.
  • 每个功能需求必须至少有一种验证方法。
  • 每个外部依赖项必须有故障模式测试或手动验证路径。
  • 每个契约必须可通过具有代表性的有效和无效输入进行测试。
  • 每个非功能需求必须包含可衡量的阈值或 
    TBD threshold
    。
  • 每个准则必须对下游实施Agent具有可操作性。

Quality Checklist

质量检查清单

Before presenting the result, verify:
  • The output is written in English.
  • The spec has clear scope and non-goals.
  • Functional behavior is separated from technical design.
  • Modules have clear responsibilities and boundaries.
  • Contracts define inputs, outputs, errors, and invariants.
  • Data ownership and lifecycle are explicit.
  • Failure modes and edge cases are included.
  • Non-functional requirements are measurable or marked as 
    TBD
    .
  • Requirements are traceable to modules, contracts, and verification.
  • The spec contains no invented project names, client names, vendors, or unnecessary concrete technologies.
在呈现结果之前，验证：
  • 输出为英文。
  • 规格文档具有明确的范围和非目标。
  • 功能行为与技术设计分离。
  • 模块具有清晰的职责和边界。
  • 契约定义了输入、输出、错误和不变量。
  • 数据所有权和生命周期明确。
  • 包含故障模式和边缘情况。
  • 非功能需求可衡量或标记为 
    TBD
    。
  • 需求可追溯到模块、契约和验证。
  • 规格文档不包含虚构的项目名称、客户名称、供应商或不必要的具体技术。

Response Style

响应风格

  • Be structured, precise, and implementation-ready without writing code.
  • Use tables for modules, contracts, decisions, risks, and traceability.
  • Use short bullets for rules, constraints, and guardrails.
  • Prefer neutral terms such as 
    domain module
    , 
    system actor
    , 
    approved provider
    , 
    external dependency
    , and 
    system of record
    .
  • Mark unknowns as 
    TBD
    and list them as open questions when they affect correctness.
  • 结构化、精确且可直接用于实施，但不编写代码。
  • 使用表格展示模块、契约、决策、风险和追溯性。
  • 使用短项目符号展示规则、约束条件和准则。
  • 优先使用中性术语，如 
    domain module
    、
    system actor
    、
    approved provider
    、
    external dependency
    和 
    system of record
    。
  • 将未知事项标记为 
    TBD
    ，当它们影响正确性时，将其列为未解决问题。