sdd-archive

SDD：归档

输入

输入	必填	描述	示例
feature_name	可选	kebab-case 格式的归档文件夹名称。若未提供，则根据 feature.md 标题生成。	jwt-authentication

步骤

步骤 0：验证输入（始终首先执行）

检查对话中是否提供了 feature_name，并检查项目根目录中是否存在 feature.md / plan.md。

• 如果 feature.md 或 plan.md 不存在 → 停止并告知用户这两个文件都是必需的。
• 记录项目根目录中是否存在 review.md —— 如果存在，该文件也会被归档。
• 记录项目根目录中是否存在 impl-summary.md —— 如果存在，该文件也会被归档。
• 如果提供了 feature_name → 将其用作归档目录名称（kebab-case）。
• 如果未提供 feature_name → 读取 feature.md，并根据 # Feature: 标题生成名称， 转换为 kebab-case（例如，“用户身份验证” → 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 部分。将新功能作为单行条目添加：

## 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 提交到版本控制