sdd-archive

SDD: アーカイブ

入力

入力	必須	説明	例
feature_name	任意	ケバブケースのアーカイブフォルダー名。省略時は feature.md の見出しから導出されます。	jwt-authentication

手順

ステップ 0: 入力の検証 (必ず最初にこれを行ってください)

会話内に feature_name があるか、またプロジェクトルートに feature.md / plan.md があるかを確認します。

• feature.md または plan.md が存在しない場合 → 停止し、両方のファイルが必要であることをユーザーに伝えます。
• プロジェクトルートに review.md が存在するかどうかを確認します — 存在する場合はアーカイブされます。
• プロジェクトルートに impl-summary.md が存在するかどうかを確認します — 存在する場合はアーカイブされます。
• feature_name が指定されている場合 → それをアーカイブディレクトリ名として使用します (ケバブケース)。
• feature_name が指定されていない場合 → feature.md を読み、# Feature: 見出しから導出し、 ケバブケースに変換します (例: "User Authentication" → user-authentication)。自動的に続行します。

---

プロセス

1. 機能名の決定

ステップ 0 の feature_name を使用します。date +"%Y%m%d%H%M" を使用して現在のタイムスタンプを取得し、それを先頭に付けてアーカイブディレクトリ名を形成します: <yyyymmddHHMM>-<feature-name> (例: 202604191430-jwt-authentication)。

2. 完了の検証

feature.md を読み、すべての受け入れ基準のチェックボックスがオンになっていることを確認します。 オフになっているものがある場合は、ユーザーに警告し、アーカイブする前に確認を求めます。

3. docs/project.md の更新

これは重要なステップです。docs/project.md を全体にわたって読み、次にアーカイブされた feature.md と plan.md を読んで、実際に何が変更されたかを抽出します。以下のセクションにわたって project.md を更新します — まだ存在しないセクションは追加してください。

3a. 機能一覧

## Features セクションを見つけるか作成します。新しい機能を 1 行のエントリとして追加します:

## Features
- **<Feature Name>**: <one-sentence description of what it does> (`docs/<feature-name>/`)

既存のリストを保持します。新しいエントリを追加します — 既存のエントリを並べ替えたり削除したりしないでください。

3b. アーキテクチャ上の決定

feature.md (未解決の質問、技術的範囲) と plan.md (アーキテクチャ上の決定) をスキャンし、 システムの構築方法に対する意味のある変更や追加を表す決定がないか探します。

該当するものの例:

• 導入された新しいアーキテクチャパターン (例: イベント駆動フローの追加、モジュールへの CQRS の導入)
• 将来の機能に影響を与える横断的な決定 (例: 「すべての認証トークンは RS256 署名を使用する」)
• 根拠を伴う、既存の規約からの意図的な逸脱
• 外部システムとの新しい統合ポイント

該当しないものの例:

• 既存の規約に従った定型的な実装上の選択
• ファイル命名やパッケージ配置の決定
• アーキテクチャの方向性を変えない軽微なリファクタリング

該当する決定については、## Architecture Decisions セクションを見つけるか作成します:

## Architecture Decisions

| Date | Decision | Rationale | Feature |
|------|----------|-----------|---------|
| <date> | <what was decided> | <why> | [<Feature Name>](docs/<feature-name>/) |

テーブルがすでに存在する場合は、新しい行を追加します。テーブルを再作成しないでください。

3c. API サーフェス (該当する場合)

機能が REST エンドポイントを追加または変更した場合は、## API セクションを見つけるか作成し、 新しいエンドポイントを文書化します:

## API
| Method | Path | Description | Auth Required |
|--------|------|-------------|---------------|
| POST | /api/v1/auth/login | Authenticate user, returns JWT | No |
| POST | /api/v1/auth/refresh | Refresh access token | Yes (refresh token) |

新規または変更されたエンドポイントのみを追加します。既存のエントリを保持します。

3d. 環境 / 設定

機能が新しい環境変数や設定キーを導入した場合は、それらを ## Environment & Configuration セクションに追加します:

## Environment & Configuration
| Key | Description | Required | Default |
|-----|-------------|----------|---------|
| JWT_SECRET | Secret key for JWT signing | Yes | — |
| JWT_EXPIRY_MINUTES | Access token TTL in minutes | No | 15 |

4. project.md の変更を表示

書き込む前に、project.md に対して行おうとしているすべての変更の概要を提示します:

## Proposed project.md Updates

### Features (1 addition)
- Added: JWT Authentication

### Architecture Decisions (1 addition)
- Added: All tokens signed with RS256; public key distributed via /.well-known/jwks.json

### API (2 additions)
- Added: POST /api/v1/auth/login
- Added: POST /api/v1/auth/refresh

### Environment & Configuration (2 additions)
- Added: JWT_SECRET
- Added: JWT_EXPIRY_MINUTES

### No changes to
- Tech Stack, Architecture overview, Conventions

書き込む前にユーザーに確認を求めます。提案された更新に対する変更をユーザーが希望する場合は、 まずその修正を適用してから書き込みます。

5. アーカイブ

以下の操作を実行します:

ARCHIVE_DIR="docs/specs-archive/$(date +"%Y%m%d%H%M")-<feature-name>"
mkdir -p "$ARCHIVE_DIR"
mv feature.md "$ARCHIVE_DIR/feature.md"
mv plan.md "$ARCHIVE_DIR/plan.md"
# move review.md only if it exists
[ -f review.md ] && mv review.md "$ARCHIVE_DIR/review.md"
# move impl-summary.md only if it exists
[ -f impl-summary.md ] && mv impl-summary.md "$ARCHIVE_DIR/impl-summary.md"

6. 簡単な概要の作成

docs/specs-archive/<yyyymmddHHMM>-<feature-name>/README.md を作成します:

# <Feature Name>

Implemented on: <date>

<Brief description of what was built, key files, and any notable decisions.>

7. 確認

最終的なサマリーをユーザーに報告します：

• docs/specs-archive/<yyyymmddHHMM>-<feature-name>/ にアーカイブされたファイル（feature.md、plan.md、review.md、および存在していた場合は impl-summary.md）
• docs/project.md で更新されたセクション
• docs/specs-archive/<yyyymmddHHMM>-<feature-name>/ と docs/project.md の両方をバージョン管理にコミットするよう促します