openspec-context-loading

规格上下文加载

发现并加载项目规格、当前变更和需求，以提供上下文。

快速开始

上下文加载有助于回答以下问题：

• 此项目中有哪些规格？
• 当前有哪些活跃变更？
• 定义了哪些需求？
• 系统具备哪些能力？
• 某个特定功能的规格在哪里？

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

发现命令

列出所有规格

# 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
# or
ls -R spec/specs/

输出格式：

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

列出活跃变更

# 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 {} \;

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

列出已归档的变更

# Show all archived changes
ls -1 spec/archive/

# Show with dates
ls -la spec/archive/

# Find recently archived (last 7 days)
find spec/archive/ -maxdepth 1 -type d -mtime -7

搜索需求

# 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

搜索场景

# 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

按关键词搜索

# Find specs mentioning "authentication"
grep -r -i "authentication" spec/specs/

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

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

常见查询

查询 1：“有哪些规格？”

# List all capabilities
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

响应格式：

## Existing Specifications

The project has specifications for the following capabilities:

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

Total: 3 capabilities, 25 requirements

查询 2：“有哪些活跃变更？”

# 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

响应格式：

## 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

查询 3：“给我看看身份验证规格”

# 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

响应格式：

## Authentication Specification

(Include full content of spec.md)

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

查询 4：“查找与密码相关的规格”

# Search for keyword
grep -r -i "password" spec/specs/ -A 5

# Show which specs mention it
grep -r -i "password" spec/specs/ -l

响应格式：

## Specs Mentioning "Password"

Found in:
- spec/specs/authentication/spec.md (3 requirements)
- spec/specs/security/spec.md (1 requirement)

Relevant requirements:
### Requirement: Password Validation
### Requirement: Password Reset
### Requirement: Password Strength

查询 5：“变更 X 中有什么？”

# 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 {} \;

仪表板视图

创建全面的项目概览：

#!/bin/bash
# Project specification dashboard

echo "===  Specification Dashboard ==="
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 ""

# 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 ""

# 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 ""

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

响应格式：

# Specification Dashboard

## Capabilities
Total capabilities: 3
  - authentication: 8 requirements
  - billing: 12 requirements
  - notifications: 5 requirements

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

## Changes
Active changes: 2
Archived changes: 15

## Recent Activity
Recently modified specs:
- spec/specs/billing/spec.md (2 days ago)
- spec/specs/authentication/spec.md (1 week ago)

高级查询

查找相关需求

# 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/

分析覆盖范围

# 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
grep -A 5 "#### Scenario:" spec/specs/**/*.md | grep -v "GIVEN\|WHEN\|THEN"

比较活跃变更与归档变更

# 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 {} \;

搜索模式

模式 1：能力发现

用户提问：“系统能做什么？”

# List capabilities
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

模式 2：功能搜索

用户提问：“有密码重置的规格吗？”

# 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

模式 3：变更跟踪

用户提问：“目前正在处理什么？”

# 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

最佳实践

模式 1：先提供上下文，再介绍细节

良好的流程：

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

模式 2：高效使用 Grep

# 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

模式 3：汇总信息

不要只是倾倒文件内容。请进行总结：

**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?"

应避免的反模式

不要：

• 未经用户请求就读取整个规格文件
• 默认列出每一项需求
• 不做格式整理就展示原始 grep 输出
• 假设用户知道能力名称

应该：

• 从高层概览开始
• 询问用户想探索哪个领域
• 清晰地整理输出格式
• 提供导航提示

参考资料

• SEARCH_PATTERNS.md - 高级 grep/find 模式

---

Token 预算：此 SKILL.md 约有 460 行，低于建议的 500 行上限。