Back to Details

speckit-analyze-zh

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

用户输入

User Input

text
$ARGUMENTS
您必须在继续之前考虑用户输入（如果不为空）。
text
$ARGUMENTS
You must consider the user input (if not empty) before proceeding.

目标

Objectives

在实现之前，识别三个核心工件（
spec.md
、
plan.md
、
tasks.md
）之间的不一致、重复、歧义和未充分说明的项目。此命令必须仅在 
speckit-tasks
成功生成完整的 
tasks.md
后运行。
Before implementation, identify inconsistent, duplicate, ambiguous, and under-specified items among the three core artifacts (
spec.md
, 
plan.md
, 
tasks.md
). This command must only be run after 
speckit-tasks
has successfully generated the complete 
tasks.md
.

操作约束

Operational Constraints

严格只读：不要修改任何文件。输出结构化分析报告。提供可选的补救计划（用户必须明确批准后才能手动调用任何后续编辑命令）。
宪章权威性：项目宪章（
.specify/memory/constitution.md
）在此分析范围内是不可协商的。宪章冲突自动为关键级别，需要调整规格、计划或任务——而不是稀释、重新解释或默默忽略原则。如果原则本身需要更改，必须在 
speckit-analyze
之外的单独、明确的宪章更新中进行。
Strictly Read-Only: Do NOT modify any files. Output a structured analysis report. Provide an optional remediation plan (users must explicitly approve before any subsequent edit commands can be manually invoked).
Charter Authority: The project charter (
.specify/memory/constitution.md
) is non-negotiable within the scope of this analysis. Charter conflicts are automatically critical-level issues, requiring adjustments to the specification, plan, or tasks—not dilution, reinterpretation, or silent disregard of principles. If the principles themselves need to be changed, this must be done in a separate, explicit charter update outside of 
speckit-analyze
.

执行步骤

Execution Steps

scripts: sh: .specify/scripts/bash/check-prerequisites.sh --json ps: .specify/scripts/powershell/check-prerequisites.ps1 -Json
scripts: sh: .specify/scripts/bash/check-prerequisites.sh --json ps: .specify/scripts/powershell/check-prerequisites.ps1 -Json

1. 初始化分析上下文

1. Initialize Analysis Context

从仓库根目录运行一次 
{SCRIPT}
并解析 JSON 以获取 FEATURE_DIR 和 AVAILABLE_DOCS。推导绝对路径：
  • SPEC = FEATURE_DIR/spec.md
  • PLAN = FEATURE_DIR/plan.md
  • TASKS = FEATURE_DIR/tasks.md
如果缺少任何必需文件，则中止并显示错误消息（指示用户运行缺少的先决条件命令）。 对于参数中的单引号，如 "I'm Groot"，使用转义语法：例如 'I'''m Groot'（或者如果可能的话使用双引号："I'm Groot"）。
Run 
{SCRIPT}
once from the repository root and parse the JSON to get FEATURE_DIR and AVAILABLE_DOCS. Derive absolute paths:
  • SPEC = FEATURE_DIR/spec.md
  • PLAN = FEATURE_DIR/plan.md
  • TASKS = FEATURE_DIR/tasks.md
Abort with an error message (instructing the user to run the missing prerequisite commands) if any required files are missing. For single quotes in arguments, such as "I'm Groot", use escape syntax: e.g., 'I'''m Groot' (or use double quotes if possible: "I'm Groot").

2. 加载工件（渐进式披露）

2. Load Artifacts (Progressive Disclosure)

仅加载每个工件的最小必要上下文：
来自 spec.md：
  • 概述/上下文
  • 功能要求
  • 非功能要求
  • 用户故事
  • 边缘情况（如果存在）
来自 plan.md：
  • 架构/技术栈选择
  • 数据模型引用
  • 阶段
  • 技术约束
来自 tasks.md：
  • 任务 ID
  • 描述
  • 阶段分组
  • 并行标记 [P]
  • 引用的文件路径
来自 constitution：
  • 加载 
    .specify/memory/constitution.md
    用于原则验证
Load only the minimal necessary context for each artifact:
From spec.md:
  • Overview/Context
  • Functional Requirements
  • Non-Functional Requirements
  • User Stories
  • Edge Cases (if present)
From plan.md:
  • Architecture/Technology Stack Selection
  • Data Model References
  • Phases
  • Technical Constraints
From tasks.md:
  • Task IDs
  • Descriptions
  • Phase Grouping
  • Parallel Marker [P]
  • Referenced File Paths
From constitution:
  • Load 
    .specify/memory/constitution.md
    for principle validation

3. 构建语义模型

3. Build Semantic Model

创建内部表示（不要在输出中包含原始工件）：
  • 要求清单：每个功能+非功能要求带有一个稳定键（根据祈使句派生 slug；例如，"用户可以上传文件" → 
    user-can-upload-file
    ）
  • 用户故事/动作清单：具有验收标准的离散用户动作
  • 任务覆盖映射：将每个任务映射到一个或多个要求或故事（通过关键词/显式引用模式如 ID 或关键词进行推断）
  • 宪章规则集：提取原则名称和 MUST/SHOULD 规范性陈述
Create an internal representation (do not include raw artifacts in output):
  • Requirements Inventory: Each functional + non-functional requirement with a stable key (derive slug from imperative; e.g., "User can upload files" → 
    user-can-upload-file
    )
  • User Stories/Actions Inventory: Discrete user actions with acceptance criteria
  • Task Coverage Mapping: Map each task to one or more requirements or stories (inferred via keywords/explicit reference patterns like IDs or keywords)
  • Charter Rule Set: Extract principle names and MUST/SHOULD normative statements

4. 检测过程（高效令牌分析）

4. Detection Process (Efficient Token Analysis)

专注于高信号发现。限制总数为 50 个发现；在溢出摘要中聚合其余发现。
Focus on high-signal findings. Limit total findings to 50; aggregate remaining findings in an overflow summary.

A. 重复检测

A. Duplication Detection

  • 识别近似重复的要求
  • 标记质量较低的措辞以进行合并
  • Identify approximately duplicate requirements
  • Flag lower-quality wording for merging

B. 歧义检测

B. Ambiguity Detection

  • 标记缺乏可测量标准的模糊形容词（快速、可扩展、安全、直观、健壮）
  • 标记未解决的占位符（TODO、TKTK、???、
    <placeholder>
    等）
  • Flag vague adjectives without measurable criteria (fast, scalable, secure, intuitive, robust)
  • Flag unresolved placeholders (TODO, TKTK, ???, 
    <placeholder>
    , etc.)

C. 未充分说明

C. Under-Specification

  • 有动词但缺少对象或可测量结果的要求
  • 缺少验收标准对齐的用户故事
  • 引用在规格/计划中未定义的文件或组件的任务
  • Requirements with verbs but missing objects or measurable outcomes
  • User stories lacking alignment with acceptance criteria
  • Tasks referencing files or components not defined in the specification/plan

D. 宪章对齐

D. Charter Alignment

  • 任何与 MUST 原则冲突的要求或计划元素
  • 缺少宪章中规定的章节或质量门
  • Any requirements or plan elements conflicting with MUST principles
  • Missing sections or quality gates mandated in the charter

E. 覆盖差距

E. Coverage Gaps

  • 没有关联任务的要求
  • 没有映射要求/故事的任务
  • 未在任务中体现的非功能要求（例如，性能、安全性）
  • Requirements with no associated tasks
  • Tasks with no mapped requirements/stories
  • Non-functional requirements not reflected in tasks (e.g., performance, security)

F. 不一致

F. Inconsistencies

  • 术语漂移（同一概念在不同文件中有不同名称）
  • 计划中引用但在规格中缺失的数据实体（反之亦然）
  • 任务排序矛盾（例如，集成任务在基础设置任务之前但没有依赖注释）
  • 冲突的要求（例如，一个要求 Next.js 而另一个指定 Vue）
  • Term drift (same concept with different names in different files)
  • Data entities referenced in the plan but missing from the specification (and vice versa)
  • Contradictory task sequencing (e.g., integration task before foundational setup task without dependency annotations)
  • Conflicting requirements (e.g., one requiring Next.js while another specifies Vue)

5. 严重性分配

5. Severity Assignment

使用此启发式方法来优先处理发现：
  • 关键：违反宪章 MUST、缺少核心规格工件，或阻塞基本功能的零覆盖要求
  • 高：重复或冲突的要求、模糊的安全/性能属性、不可测试的验收标准
  • 中：术语漂移、缺少非功能任务覆盖、未充分说明的边缘情况
  • 低：样式/措辞改进、不影响执行顺序的次要冗余
Use this heuristic to prioritize findings:
  • Critical: Violation of charter MUSTs, missing core specification artifacts, or zero-coverage requirements blocking basic functionality
  • High: Duplicate or conflicting requirements, vague security/performance attributes, untestable acceptance criteria
  • Medium: Term drift, missing non-functional task coverage, under-specified edge cases
  • Low: Style/wording improvements, minor redundancies that do not impact execution order

6. 生成紧凑分析报告

6. Generate Compact Analysis Report

输出一个 Markdown 报告（不写入文件）具有以下结构：
Output a Markdown report (do not write to file) with the following structure:

规格分析报告

Specification Analysis Report

ID类别严重性位置摘要建议
A1重复高spec.md:L120-134两个相似的要求 ...合并措辞；保留更清晰的版本
（每项发现添加一行；生成以类别首字母为前缀的稳定 ID。）
覆盖摘要表：
要求键有任务？任务 ID备注
宪章对齐问题：（如果有）
未映射的任务：（如果有）
指标：
  • 总要求
  • 总任务
  • 覆盖率%（有>=1个任务的要求）
  • 歧义计数
  • 重复计数
  • 关键问题计数
IDCategorySeverityLocationSummaryRecommendation
A1DuplicationHighspec.md:L120-134Two similar requirements ...Merge wording; retain the clearer version
(Add one row per finding; generate stable IDs prefixed with the category initial.)
Coverage Summary Table:
Requirement KeyHas Task?Task IDNotes
Charter Alignment Issues: (if any)
Unmapped Tasks: (if any)
Metrics:
  • Total Requirements
  • Total Tasks
  • Coverage % (requirements with >=1 task)
  • Ambiguity Count
  • Duplication Count
  • Critical Issue Count

7. 提供下一步行动

7. Provide Next Steps

在报告末尾，输出一个简洁的下一步行动块：
  • 如果存在关键问题：建议在 
    speckit-implement
    之前解决
  • 如果只有低/中等：用户可以继续，但提供改进建议
  • 提供明确的命令建议：例如，"使用改进运行 
    speckit-specify
    "，"运行 
    speckit-plan
    调整架构"，"手动编辑 tasks.md 添加 'performance-metrics' 的覆盖"
At the end of the report, output a concise next steps block:
  • If critical issues exist: Recommend resolving before 
    speckit-implement
  • If only low/medium issues: User may proceed, but provide improvement suggestions
  • Provide explicit command recommendations: e.g., "Run 
    speckit-specify
    with improvements", "Run 
    speckit-plan
    to adjust architecture", "Manually edit tasks.md to add coverage for 'performance-metrics'"

8. 提供补救措施

8. Provide Remediation

询问用户："您希望我为前 N 个问题建议具体的补救编辑吗？"（不要自动应用它们。）
Ask the user: "Would you like me to suggest specific remediation edits for the top N issues?" (Do not apply them automatically.)

操作原则

Operational Principles

上下文效率

Context Efficiency

  • 最小高信号令牌：专注于可操作的发现，而不是详尽的文档
  • 渐进式披露：增量加载工件；不要将所有内容倒入分析
  • 高效令牌输出：限制发现表为 50 行；总结溢出
  • 确定性结果：在没有更改的情况下重新运行应产生一致的 ID 和计数
  • Minimum High-Signal Tokens: Focus on actionable findings rather than exhaustive documentation
  • Progressive Disclosure: Incrementally load artifacts; do not dump everything into analysis
  • Efficient Token Output: Limit findings table to 50 rows; summarize overflow
  • Deterministic Results: Re-running without changes should produce consistent IDs and counts

分析指南

Analysis Guidelines

  • 永不修改文件（这是只读分析）
  • 永不虚构缺失部分（如果缺失，准确报告）
  • 优先处理宪章违规（这些总是关键的）
  • 使用示例而非详尽规则（引用具体实例，而非通用模式）
  • 优雅报告零问题（发出带有覆盖统计的成功报告）
  • Never Modify Files (this is read-only analysis)
  • Never Invent Missing Sections (report accurately if missing)
  • Prioritize Charter Violations (these are always critical)
  • Use Examples Instead of Exhaustive Rules (cite specific instances, not generic patterns)
  • Gracefully Report Zero Issues (issue a success report with coverage statistics)

上下文

Context

{ARGS}
{ARGS}