openspec-archiving

仕様のアーカイブ

完了した変更提案をアーカイブし、その仕様差分を現行の仕様ドキュメントに統合します。

クイックスタート

アーカイブでは、次の 2 つの主な操作を行います。

1. 変更フォルダーを移動して、タイムスタンプ付きでアーカイブする
2. 仕様差分を統合して、現行の仕様に反映する（ADDED／MODIFIED／REMOVED 操作）

重要なルール：アーカイブする前に、すべてのタスクが完了していることを確認してください。アーカイブは、デプロイと完了を意味します。

ワークフロー

このチェックリストをコピーして、進捗を記録してください。

Archive Progress:
- [ ] Step 1: Verify implementation is complete
- [ ] Step 2: Review spec deltas to merge
- [ ] Step 3: Create timestamped archive directory
- [ ] Step 4: Merge ADDED requirements into living specs
- [ ] Step 5: Merge MODIFIED requirements into living specs
- [ ] Step 6: Merge REMOVED requirements into living specs
- [ ] Step 7: Move change folder to archive
- [ ] Step 8: Validate living spec structure

Step 1: 実装が完了していることを確認する

アーカイブする前に、すべての作業が完了していることを確認してください。

# Check for IMPLEMENTED marker
test -f spec/changes/{change-id}/IMPLEMENTED && echo "✓ Implemented" || echo "✗ Not implemented"

# Review tasks
cat spec/changes/{change-id}/tasks.md

# Check git status for uncommitted work
git status

ユーザーに確認する：

Are all tasks complete and tested?
Has this change been deployed to production?
Should I proceed with archiving?

Step 2: 統合する仕様差分を確認する

何が統合されるのかを把握してください。

# List all spec delta files
find spec/changes/{change-id}/specs -name "*.md" -type f

# Read each delta
for file in spec/changes/{change-id}/specs/**/*.md; do
    echo "=== $file ==="
    cat "$file"
done

確認する項目：

• 影響を受ける機能
• ADDED／MODIFIED／REMOVED となる要件の数
• 現行の仕様のどこに変更を反映するか

Step 3: タイムスタンプ付きのアーカイブディレクトリを作成する

# Create archive with today's date
TIMESTAMP=$(date +%Y-%m-%d)
mkdir -p spec/archive/${TIMESTAMP}-{change-id}

例：

# For change "add-user-auth" archived on Oct 26, 2025
mkdir -p spec/archive/2025-10-26-add-user-auth

Step 4: ADDED 要件を現行の仕様に統合する

各 ## ADDED Requirements セクションについて、次の手順を実行します。

手順：

1. 対象となる現行の仕様ファイルを特定します
2. 新しい要件をファイルの末尾に追加します
3. 適切な Markdown 形式を維持します

例：

ソース（spec/changes/add-user-auth/specs/authentication/spec-delta.md）：

## ADDED Requirements

### Requirement: User Login
WHEN a user submits valid credentials,
the system SHALL authenticate the user and create a session.

#### Scenario: Successful Login
GIVEN valid credentials
WHEN user submits login form
THEN system creates session

対象（spec/specs/authentication/spec.md）：

# Append to living spec
cat >> spec/specs/authentication/spec.md << 'EOF'

### Requirement: User Login
WHEN a user submits valid credentials,
the system SHALL authenticate the user and create a session.

#### Scenario: Successful Login
GIVEN valid credentials
WHEN user submits login form
THEN system creates session
EOF

Step 5: MODIFIED 要件を現行の仕様に統合する

各 ## MODIFIED Requirements セクションについて、次の手順を実行します。

手順：

1. 現行の仕様内で既存の要件を特定します
2. 要件ブロック全体（すべてのシナリオを含む）を置き換えます
3. 差分に記載されている更新済みのテキスト全体を使用します

sed を使用する例：

# Find and replace requirement block
# This is conceptual - actual implementation depends on structure

# First, identify the line range of the old requirement
START_LINE=$(grep -n "### Requirement: User Login" spec/specs/authentication/spec.md | cut -d: -f1)

# Find the end (next requirement or end of file)
END_LINE=$(tail -n +$((START_LINE + 1)) spec/specs/authentication/spec.md | \
           grep -n "^### Requirement:" | head -1 | cut -d: -f1)

# Delete old requirement
sed -i "${START_LINE},${END_LINE}d" spec/specs/authentication/spec.md

# Insert new requirement at same position
# (Extract from delta and insert)

手動で行う方法（安全性を重視する場合に推奨）：

1. Open living spec in editor
2. Find the requirement by name
3. Delete entire block (requirement + all scenarios)
4. Paste updated requirement from delta
5. Save

Step 6: REMOVED 要件を現行の仕様から削除する

各 ## REMOVED Requirements セクションについて、次の手順を実行します。

手順：

1. 現行の仕様内で要件を特定します
2. 要件ブロック全体を削除します
3. 削除内容を記録するコメントを追加します

例：

# Option 1: Delete with comment
# Manually edit spec/specs/authentication/spec.md

# Add deprecation comment
echo "" >> spec/specs/authentication/spec.md

# Delete the requirement block manually or with sed

パターン：

~~### Requirement: SMS Password Reset~~

Step 7: 変更フォルダーをアーカイブに移動する

すべての差分を統合した後、次の操作を行います。

# Move entire change folder to archive
mv spec/changes/{change-id} spec/archive/${TIMESTAMP}-{change-id}

移動が成功したことを確認する：

# Check archive exists
ls -la spec/archive/${TIMESTAMP}-{change-id}

# Check changes directory is clean
ls spec/changes/ | grep "{change-id}"  # Should return nothing

Step 8: 現行の仕様の構造を検証する

統合後、現行の仕様が正しい形式になっていることを検証します。

# Check requirement format
grep -n "### Requirement:" spec/specs/**/*.md

# Check scenario format
grep -n "#### Scenario:" spec/specs/**/*.md

# Count requirements per spec
for spec in spec/specs/**/spec.md; do
    count=$(grep -c "### Requirement:" "$spec")
    echo "$spec: $count requirements"
done

手動で確認する項目：

• 変更した各仕様ファイルを開きます
• Markdown の形式が正しいことを確認します
• 要件が論理的な流れになっていることを確認します
• 要件が重複していないことを確認します

統合ロジックのリファレンス

ADDED 操作

Action: Append to living spec
Location: End of file (before any footer/appendix)
Format: Copy requirement + all scenarios exactly as written

MODIFIED 操作

Action: Replace existing requirement
Location: Find by requirement name, replace entire block
Format: Use complete updated text from delta (don't merge, replace)
Note: Old version is preserved in archive

REMOVED 操作

Action: Delete requirement, add deprecation comment
Location: Find by requirement name
Format: Delete entire block, optionally add 

RENAMED 操作（まれ）

Action: Update requirement name, keep content
Location: Find by old name, update to new name
Format: Just change the header: ### Requirement: NewName
Note: Typically use MODIFIED instead

ベストプラクティス

パターン 1：移動前に検証する

アーカイブに移動する前に、必ず差分の統合内容を検証してください。

# After merging, check diff
git diff spec/specs/

# Review changes
git diff spec/specs/authentication/spec.md

# If correct, commit
git add spec/specs/
git commit -m "Merge spec deltas from add-user-auth"

# Then archive
mv spec/changes/add-user-auth spec/archive/2025-10-26-add-user-auth

パターン 2：アーカイブを一括で行う

個々のファイルではなく、変更全体をアーカイブします。

推奨：

# Move complete change folder
mv spec/changes/add-user-auth spec/archive/2025-10-26-add-user-auth

非推奨：

# Don't cherry-pick files
mv spec/changes/add-user-auth/proposal.md spec/archive/
# (leaves orphaned files)

パターン 3：アーカイブを保持する

アーカイブは履歴記録です。アーカイブ済みのファイルは変更しないでください。

❌ Don't: Edit files in spec/archive/
✓ Do: Treat archive as read-only history

パターン 4：Git のコミット戦略

推奨するコミットのワークフロー：

# Commit 1: Merge deltas
git add spec/specs/
git commit -m "Merge spec deltas from add-user-auth

- Added User Login requirement
- Modified Password Policy requirement
- Removed Legacy Auth requirement"

# Commit 2: Archive change
git add spec/archive/ spec/changes/
git commit -m "Archive add-user-auth change"

詳細

複雑な差分について：reference/MERGE_LOGIC.md を参照してください。

競合の解決：複数の変更によって同じ要件が変更されている場合は、手動での統合が必要です。

ロールバック戦略：アーカイブをロールバックするには、逆の手順を行います（アーカイブから changes に戻し、現行の仕様から統合した内容を削除します）。

よくあるパターン

パターン 1：単純な追加

Change adds 1 new requirement → Append to spec → Archive

パターン 2：動作の変更

Change modifies 1 requirement → Replace in spec → Archive

パターン 3：非推奨化

Change removes 1 requirement → Delete from spec with comment → Archive

パターン 4：複数の要件を持つ機能

Change adds 5 requirements across 2 specs
→ Append each to respective spec
→ Verify all are merged
→ Archive

避けるべきアンチパターン

しないでください：

• 未完了の実装をアーカイブする
• デプロイ前に差分をマージする
• アーカイブ済みファイルを変更する
• マージ後の検証を省略する
• マージした仕様を git commit し忘れる

してください：

• アーカイブする前に、すべてのタスクが完了していることを確認する
• 差分を慎重かつ完全にマージする
• アーカイブを変更不可の履歴として扱う
• マージした仕様の構造を検証する
• アーカイブへの移動前に、マージした仕様をコミットする

トラブルシューティング

問題：マージコンフリクト（要件が現行の仕様に存在する）

解決方法：

1. If names match but content differs → Use MODIFIED pattern
2. If truly different requirements → Rename one
3. If duplicate by mistake → Use whichever is correct

問題：変更または削除する要件が見つからない

解決方法：

1. Search by partial name: grep -i "login" spec/specs/**/*.md
2. Check if already removed
3. Check if in different capability file

問題：マージ後に現行の仕様で書式エラーが発生する

解決方法：

1. Fix formatting manually
2. Re-run validation: grep -n "###" spec/specs/**/*.md
3. Ensure consistent heading levels

参考資料

• MERGE_LOGIC.md - マージ操作の詳細なルール

---

トークン予算：この SKILL.md は約 480 行で、推奨上限の 500 行を下回っています。