openspec-context-loading

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Specification Context Loading

规范上下文加载

Discovers and loads project specifications, active changes, and requirements to provide context.

发现并加载项目规范、活跃变更与需求，以提供上下文信息。

Quick Start

快速开始

Context loading helps answer:

What specs exist in this project?
What changes are currently active?
What requirements are defined?
What capabilities does the system have?
Where is a specific feature specified?

Basic pattern: Search → Read → Summarize

上下文加载可帮助解答以下问题：

本项目中有哪些规范？
当前有哪些活跃变更？
定义了哪些需求？
系统具备哪些功能？
特定功能的规范位于何处？

基本模式：搜索 → 读取 → 总结

Discovery Commands

发现命令

List All Specifications

列出所有规范

bash

undefined

bash

undefined

Find all spec files

查找所有规范文件

find spec/specs -name "spec.md" -type f

Find all capability directories

查找所有功能目录

find spec/specs -mindepth 1 -maxdepth 1 -type d

Show spec tree

显示规范目录树

tree spec/specs/ # if tree is installed

tree spec/specs/ # 需安装tree工具

or

或

ls -R spec/specs/


**Output format**:

spec/specs/ ├── authentication/ │ └── spec.md ├── billing/ │ └── spec.md └── notifications/ └── spec.md

undefined

ls -R spec/specs/


**输出格式**:

spec/specs/ ├── authentication/ │ └── spec.md ├── billing/ │ └── spec.md └── notifications/ └── spec.md

undefined

List Active Changes

列出活跃变更

bash

undefined

bash

undefined

Show all active changes

显示所有活跃变更

find spec/changes -maxdepth 1 -type d -not -path "spec/changes" -not -path "*/archive" | sort

Show with modification dates

显示带修改日期的活跃变更

find spec/changes -maxdepth 1 -type d -not -path "spec/changes" -not -path "*/archive" -exec ls -ld {} ;

find spec/changes -maxdepth 1 -type d -not -path "spec/changes" -not -path "*/archive" -exec ls -ld {} \;

Count active changes

统计活跃变更数量

find spec/changes -maxdepth 1 -type d -not -path "spec/changes" -not -path "*/archive" | wc -l

undefined

find spec/changes -maxdepth 1 -type d -not -path "spec/changes" -not -path "*/archive" | wc -l

undefined

List Archived Changes

列出已归档变更

bash

undefined

bash

undefined

Show all archived changes

显示所有已归档变更

ls -1 spec/archive/

Show with dates

显示带日期的已归档变更

ls -la spec/archive/

Find recently archived (last 7 days)

查找最近7天内归档的变更

find spec/archive/ -maxdepth 1 -type d -mtime -7

undefined

find spec/archive/ -maxdepth 1 -type d -mtime -7

undefined

Search for Requirements

搜索需求

bash

undefined

bash

undefined

Find all requirements

查找所有需求

grep -r "### Requirement:" spec/specs/

Find requirements in specific capability

查找特定功能下的需求

grep "### Requirement:" spec/specs/authentication/spec.md

List unique requirement names

列出唯一的需求名称

grep -h "### Requirement:" spec/specs/**/*.md | sed 's/### Requirement: //' | sort

undefined

grep -h "### Requirement:" spec/specs/**/*.md | sed 's/### Requirement: //' | sort

undefined

Search for Scenarios

搜索场景

bash

undefined

bash

undefined

Find all scenarios

查找所有场景

grep -r "#### Scenario:" spec/specs/

Count scenarios per spec

统计每个规范下的场景数量

for spec in spec/specs/**/spec.md; do count=$(grep -c "#### Scenario:" "$spec") echo "$spec: $count scenarios" done

undefined

for spec in spec/specs/**/spec.md; do count=$(grep -c "#### Scenario:" "$spec") echo "$spec: $count scenarios" done

undefined

Search by Keyword

按关键词搜索

bash

undefined

bash

undefined

Find specs mentioning "authentication"

查找提及"authentication"的规范

grep -r -i "authentication" spec/specs/

Find requirements about "password"

查找与"password"相关的需求

grep -B 1 -A 5 -i "password" spec/specs/**/*.md | grep -A 5 "### Requirement:"

Find scenarios about "error"

查找与"error"相关的场景

grep -B 1 -A 10 -i "error" spec/specs/**/*.md | grep -A 10 "#### Scenario:"

undefined

grep -B 1 -A 10 -i "error" spec/specs/**/*.md | grep -A 10 "#### Scenario:"

undefined

Common Queries

常见查询

Query 1: "What specs exist?"

查询1："本项目中有哪些规范？"

bash

undefined

bash

undefined

List all capabilities

列出所有功能

find spec/specs -mindepth 1 -maxdepth 1 -type d -exec basename {} ;

find spec/specs -mindepth 1 -maxdepth 1 -type d -exec basename {} \;

Count requirements per capability

统计每个功能下的需求数量

for cap in spec/specs/*/; do name=$(basename "$cap") count=$(grep -c "### Requirement:" "$cap/spec.md" 2>/dev/null || echo "0") echo "$name: $count requirements" done


**Response format**:
```markdown

for cap in spec/specs/*/; do name=$(basename "$cap") count=$(grep -c "### Requirement:" "$cap/spec.md" 2>/dev/null || echo "0") echo "$name: $count requirements" done


**响应格式**:
```markdown

Existing Specifications

现有规范

The project has specifications for the following capabilities:

authentication: 8 requirements
billing: 12 requirements
notifications: 5 requirements

Total: 3 capabilities, 25 requirements

undefined

本项目针对以下功能制定了规范：

authentication：8项需求
billing：12项需求
notifications：5项需求

总计：3个功能，25项需求

undefined

Query 2: "What changes are active?"

查询2："当前有哪些活跃变更？"

bash

undefined

bash

undefined

List with proposal summaries

列出带提案摘要的活跃变更

for change in spec/changes/*/; do if [ "$change" != "spec/changes/archive/" ]; then id=$(basename "$change") echo "=== $id ===" head -n 20 "$change/proposal.md" | grep -A 3 "## Why" fi done


**Response format**:
```markdown

for change in spec/changes/*/; do if [ "$change" != "spec/changes/archive/" ]; then id=$(basename "$change") echo "=== $id ===" head -n 20 "$change/proposal.md" | grep -A 3 "## Why" fi done


**响应格式**:
```markdown

Active Changes

活跃变更

Currently active changes:

当前活跃变更如下：

add-user-auth

Why: Users need secure authentication...

原因：用户需要安全的身份验证机制...

update-billing-api

Why: Payment processing requires v2 API...

Total: 2 active changes

undefined

原因：支付流程需要升级至v2版本API...

总计：2项活跃变更

undefined

Query 3: "Show me the authentication spec"

查询3："展示authentication规范"

bash

undefined

bash

undefined

Read full spec

读取完整规范

cat spec/specs/authentication/spec.md

Or show summary

或显示摘要

echo "Requirements:" grep "### Requirement:" spec/specs/authentication/spec.md

echo "\nScenarios:" grep "#### Scenario:" spec/specs/authentication/spec.md


**Response format**:
```markdown

echo "需求列表：" grep "### Requirement:" spec/specs/authentication/spec.md

echo "
场景列表：" grep "#### Scenario:" spec/specs/authentication/spec.md


**响应格式**:
```markdown

Authentication Specification

Authentication规范

(Include full content of spec.md)

Summary:

8 requirements
16 scenarios
Last modified: [date from git log]

undefined

（包含spec.md的完整内容）

摘要：

8项需求
16个场景
最后修改时间：[来自git log的日期]

undefined

Query 4: "Find specs about password"

查询4："查找与password相关的规范"

bash

undefined

bash

undefined

Search for keyword

搜索关键词

grep -r -i "password" spec/specs/ -A 5

Show which specs mention it

显示提及该关键词的规范文件

grep -r -i "password" spec/specs/ -l


**Response format**:
```markdown

grep -r -i "password" spec/specs/ -l


**响应格式**:
```markdown

Specs Mentioning "Password"

提及"Password"的规范

Found in:

spec/specs/authentication/spec.md (3 requirements)
spec/specs/security/spec.md (1 requirement)

Relevant requirements:

在以下文件中找到相关内容：

spec/specs/authentication/spec.md（3项需求）
spec/specs/security/spec.md（1项需求）

Requirement: Password Validation

Requirement: Password Reset

Requirement: Password Strength

undefined

undefined

Query 5: "What's in change X?"

查询5："变更X包含哪些内容？"

bash

undefined

bash

undefined

Show full change context

显示完整的变更上下文

CHANGE_ID="add-user-auth"

echo "=== Proposal ===" cat spec/changes/$CHANGE_ID/proposal.md

echo "\n=== Tasks ===" cat spec/changes/$CHANGE_ID/tasks.md

echo "\n=== Spec Deltas ===" find spec/changes/$CHANGE_ID/specs -name "*.md" -exec echo "File: {}" ; -exec cat {} ;

undefined

CHANGE_ID="add-user-auth"

echo "=== 提案 ===" cat spec/changes/$CHANGE_ID/proposal.md

echo "
=== 任务 ===" cat spec/changes/$CHANGE_ID/tasks.md

echo "
=== 规范差异 ===" find spec/changes/$CHANGE_ID/specs -name "*.md" -exec echo "文件: {}" \; -exec cat {} \;

undefined

Dashboard View

仪表板视图

Create a comprehensive project overview:

bash

#!/bin/bash

创建全面的项目概览：

bash

#!/bin/bash

Project specification dashboard

项目规范仪表板

echo "=== Specification Dashboard ===" echo ""

echo "=== 规范仪表板 ===" echo ""

Capabilities

功能模块

echo "## Capabilities" CAPS=$(find spec/specs -mindepth 1 -maxdepth 1 -type d | wc -l) echo "Total capabilities: $CAPS" for cap in spec/specs/*/; do name=$(basename "$cap") reqs=$(grep -c "### Requirement:" "$cap/spec.md" 2>/dev/null || echo "0") echo " - $name: $reqs requirements" done echo ""

echo "## 功能模块" CAPS=$(find spec/specs -mindepth 1 -maxdepth 1 -type d | wc -l) echo "总功能模块数：$CAPS" for cap in spec/specs/*/; do name=$(basename "$cap") reqs=$(grep -c "### Requirement:" "$cap/spec.md" 2>/dev/null || echo "0") echo " - $name: $reqs项需求" done echo ""

Requirements

需求统计

echo "## Requirements" TOTAL_REQS=$(grep -r "### Requirement:" spec/specs/ | wc -l) TOTAL_SCENARIOS=$(grep -r "#### Scenario:" spec/specs/ | wc -l) echo "Total requirements: $TOTAL_REQS" echo "Total scenarios: $TOTAL_SCENARIOS" echo "Avg scenarios per requirement: $(echo "scale=1; $TOTAL_SCENARIOS/$TOTAL_REQS" | bc)" echo ""

echo "## 需求统计" TOTAL_REQS=$(grep -r "### Requirement:" spec/specs/ | wc -l) TOTAL_SCENARIOS=$(grep -r "#### Scenario:" spec/specs/ | wc -l) echo "总需求数：$TOTAL_REQS" echo "总场景数：$TOTAL_SCENARIOS" echo "每项需求平均场景数：$(echo "scale=1; $TOTAL_SCENARIOS/$TOTAL_REQS" | bc)" echo ""

Changes

变更统计

echo "## Changes" ACTIVE=$(find spec/changes -maxdepth 1 -type d -not -path "spec/changes" -not -path "*/archive" | wc -l) ARCHIVED=$(ls -1 spec/archive/ | wc -l) echo "Active changes: $ACTIVE" echo "Archived changes: $ARCHIVED" echo ""

echo "## 变更统计" ACTIVE=$(find spec/changes -maxdepth 1 -type d -not -path "spec/changes" -not -path "*/archive" | wc -l) ARCHIVED=$(ls -1 spec/archive/ | wc -l) echo "活跃变更数：$ACTIVE" echo "已归档变更数：$ARCHIVED" echo ""

Recent activity

近期活动

echo "## Recent Activity" echo "Recently modified specs:" find spec/specs -name "spec.md" -type f -exec ls -lt {} ; | head -5


**Response format**:
```markdown

echo "## 近期活动" echo "最近修改的规范：" find spec/specs -name "spec.md" -type f -exec ls -lt {} \; | head -5


**响应格式**:
```markdown

Specification Dashboard

规范仪表板

Capabilities

功能模块

Total capabilities: 3

authentication: 8 requirements
billing: 12 requirements
notifications: 5 requirements

总功能模块数：3

authentication：8项需求
billing：12项需求
notifications：5项需求

Requirements

需求统计

Total requirements: 25 Total scenarios: 52 Avg scenarios per requirement: 2.1

总需求数：25 总场景数：52 每项需求平均场景数：2.1

Changes

变更统计

Active changes: 2 Archived changes: 15

活跃变更数：2 已归档变更数：15

Recent Activity

近期活动

Recently modified specs:

spec/specs/billing/spec.md (2 days ago)
spec/specs/authentication/spec.md (1 week ago)

undefined

Advanced Queries

高级查询

Find Related Requirements

查找相关需求

bash

undefined

bash

undefined

Find requirements that mention another requirement

查找提及其他需求的需求

grep -r "User Login" spec/specs/ -A 10 | grep "### Requirement:"

Find cross-references

查找交叉引用

grep -r "See Requirement:" spec/specs/

undefined

grep -r "See Requirement:" spec/specs/

undefined

Analyze Coverage

分析覆盖情况

bash

undefined

bash

undefined

Find requirements without scenarios

查找无对应场景的需求

for spec in spec/specs/**/spec.md; do awk '/### Requirement:/ {req=$0; getline; if ($0 !~ /#### Scenario:/) print req}' "$spec" done

Find scenarios without proper Given/When/Then

查找未遵循Given/When/Then格式的场景

grep -A 5 "#### Scenario:" spec/specs/**/*.md | grep -v "GIVEN|WHEN|THEN"

undefined

grep -A 5 "#### Scenario:" spec/specs/**/*.md | grep -v "GIVEN\|WHEN\|THEN"

undefined

Compare Active vs Archive

对比活跃变更与归档变更

bash

undefined

bash

undefined

Show evolution over time

显示变更历史

echo "Archive history:" ls -1 spec/archive/ | head -10

echo "Recent archives (last 30 days):" find spec/archive/ -maxdepth 1 -type d -mtime -30 -exec basename {} ;

undefined

echo "归档历史：" ls -1 spec/archive/ | head -10

echo "最近30天内的归档变更：" find spec/archive/ -maxdepth 1 -type d -mtime -30 -exec basename {} \;

undefined

Search Patterns

搜索模式

Pattern 1: Capability Discovery

模式1：功能发现

User asks: "What can the system do?"

bash

undefined

用户提问："系统能实现哪些功能？"

bash

undefined

List capabilities

列出所有功能

find spec/specs -mindepth 1 -maxdepth 1 -type d -exec basename {} ;

find spec/specs -mindepth 1 -maxdepth 1 -type d -exec basename {} \;

Show high-level requirements

显示高级需求摘要

for cap in spec/specs/*/; do echo "=== $(basename $cap) ===" grep "### Requirement:" "$cap/spec.md" | head -3 done

undefined

for cap in spec/specs/*/; do echo "=== $(basename $cap) ===" grep "### Requirement:" "$cap/spec.md" | head -3 done

undefined

Pattern 2: Feature Search

模式2：功能搜索

User asks: "Is there a spec for password reset?"

bash

undefined

用户提问："是否有密码重置的规范？"

bash

undefined

Search for keyword

搜索关键词

grep -r -i "password reset" spec/specs/ -B 1 -A 10

If found, show full requirement

如果找到，显示完整需求

grep -B 1 -A 20 "Requirement:.Password Reset" spec/specs/**/.md

undefined

grep -B 1 -A 20 "Requirement:.Password Reset" spec/specs/**/.md

undefined

Pattern 3: Change Tracking

模式3：变更跟踪

User asks: "What's being worked on?"

bash

undefined

用户提问："当前正在进行哪些工作？"

bash

undefined

Show active changes with status

显示带状态的活跃变更

for change in spec/changes/*/; do if [ "$change" != "spec/changes/archive/" ]; then id=$(basename "$change") echo "$id:" test -f "$change/IMPLEMENTED" && echo " Status: Implemented" || echo " Status: In Progress" echo " Tasks: $(grep -c "^[0-9]+." "$change/tasks.md")" fi done

undefined

for change in spec/changes/*/; do if [ "$change" != "spec/changes/archive/" ]; then id=$(basename "$change") echo "$id:" test -f "$change/IMPLEMENTED" && echo " 状态：已实现" || echo " 状态：进行中" echo " 任务数：$(grep -c "^[0-9]\+\." "$change/tasks.md")" fi done

undefined

Best Practices

最佳实践

Pattern 1: Provide Context Before Details

模式1：先提供上下文再展示细节

Good flow:

markdown

1. Show dashboard (high-level overview)
2. User asks about specific capability
3. Show that capability's requirements
4. User asks about specific requirement
5. Show full requirement with scenarios

良好流程:

markdown

1. 展示仪表板（高级概览）
2. 用户询问特定功能
3. 展示该功能的需求
4. 用户询问特定需求
5. 展示带场景的完整需求

Pattern 2: Use Grep Efficiently

模式2：高效使用Grep

bash

undefined

bash

undefined

Combine filters for precision

组合过滤器提高精度

grep -r "### Requirement:" spec/specs/ | grep -i "auth"

Use context flags for readability

使用上下文参数提升可读性

grep -B 2 -A 10 "#### Scenario:" spec/specs/authentication/spec.md

undefined

grep -B 2 -A 10 "#### Scenario:" spec/specs/authentication/spec.md

undefined

Pattern 3: Aggregate Information

模式3：汇总信息

Don't just dump file contents. Summarize:

markdown

**Bad**: (dump entire spec file)

**Good**:
"The authentication spec has 8 requirements covering:
- User login
- Password management
- Session handling
- Multi-factor authentication

Would you like details on any specific requirement?"

不要直接输出文件内容，应进行总结：

markdown

**错误示例**：（直接输出完整规范文件）

**正确示例**:
"身份验证规范包含8项需求，覆盖以下领域：
- 用户登录
- 密码管理
- 会话处理
- 多因素身份验证

是否需要查看特定需求的详细信息？"

Anti-Patterns to Avoid

需避免的反模式

Don't:

Read entire spec files without user request
List every single requirement by default
Show raw grep output without formatting
Assume user knows capability names

Do:

Start with high-level overview
Ask which area user wants to explore
Format output clearly
Provide navigation hints

请勿:

未经用户请求就读取完整规范文件
默认列出每一项需求
直接展示原始grep输出而不格式化
假设用户知晓功能模块名称

请:

从高级概览开始
询问用户想探索的领域
清晰格式化输出内容
提供导航提示

Reference Materials

参考资料

SEARCH_PATTERNS.md - Advanced grep/find patterns

Token budget: This SKILL.md is approximately 460 lines, under the 500-line recommended limit.

SEARCH_PATTERNS.md - 高级grep/find模式

Token预算：本SKILL.md约460行，低于推荐的500行限制。",