OpenSpec 引入了革命性的双文件夹架构设计：openspec/specs/ 文件夹维护当前的事实来源（已批准的权威规范），
而 openspec/changes/ 文件夹则包含所有提议的更新和变更。这种清晰的分离使得代码差异保持明确和易于管理，
特别适合需要持续演进的功能开发场景。与传统的单一规范文件方法不同，OpenSpec 将每个功能变更的所有相关内容
（提案、任务、设计文档、规范增量）都组织在一个独立的变更文件夹中，这使得它在处理棕地项目改造（1→n 开发模式）时
表现出色，能够精确追踪每一处变更的来龙去脉。
openspec/changes/ 目录下生成一个新的变更文件夹，其中包含提案文档、
任务列表和规范增量。这个阶段的重点是捕获意图，而不是立即开始编码。
openspec/specs/ 中的源规范文件，然后将变更文件夹移至归档目录。
这一步非常重要，它确保事实来源始终保持最新。
openspec/AGENTS.md 文件支持其他 AI 工具。
这些工具可以读取 AGENTS.md 中的指令，并通过自然语言来使用 OpenSpec 功能。
### Requirement: [名称] 格式#### Scenario: 块SHALL 或 MUST 表示强制性要求
我们有一个在线 SaaS 平台，当前只支持邮箱+密码登录。由于安全性要求提升，产品团队决定添加双因素认证功能。
现有的认证规范位于 openspec/specs/auth/spec.md，我们需要在不破坏现有功能的前提下添加 2FA 支持。
$ npm install -g @fission-ai/openspec@latest
$ openspec --version
$ cd my-saas-platform
$ openspec init
openspec/project.md 中定义项目约定和技术栈信息，帮助 AI 更好地理解项目上下文。
# Project: SaaS Platform ## Tech Stack - Backend: Node.js + Express + TypeScript - Database: PostgreSQL - Authentication: JWT tokens - Frontend: React + TypeScript ## Conventions - Use async/await for all async operations - Follow REST API design principles - All endpoints must have proper error handling - Security: OWASP Top 10 compliance required
my-saas-platform/ ├── openspec/ │ ├── project.md # 项目上下文（新创建） │ ├── AGENTS.md # AI 工具协议（自动生成） │ ├── specs/ # 源规范文件夹 │ │ └── auth/ │ │ └── spec.md # 现有的认证规范 │ ├── changes/ # 变更文件夹（空） │ └── archive/ # 归档文件夹（空） ├── .claude/ │ └── commands/ │ ├── openspec-proposal.md │ ├── openspec-apply.md │ └── openspec-archive.md └── ...
openspec/changes/add-2fa-authentication/
├── proposal.md # 变更提案
├── tasks.md # 实施任务清单
├── design.md # 技术设计（AI 生成）
└── specs/
└── auth/
└── spec.md # 规范增量（Delta）
# Change Proposal: Add Two-Factor Authentication ## Problem Statement Current authentication relies solely on email/password, which is vulnerable to credential theft. Users need an additional security layer. ## Proposed Solution Implement TOTP-based two-factor authentication using authenticator apps. Include recovery code mechanism for account recovery. ## Impact Analysis - **Affected Specs**: auth/spec.md - **New Features**: 2FA setup, verification, recovery codes - **Modified Features**: Login flow now includes optional 2FA step - **Security Impact**: Significantly reduces account takeover risk ## Success Criteria - Users can enable/disable 2FA from settings - Login requires 2FA code when enabled - Recovery codes provide backup access method - No breaking changes to existing authentication
# Implementation Tasks ## Backend Tasks - [ ] Add 2FA fields to user database schema - [ ] Implement TOTP secret generation - [ ] Create API endpoint: POST /api/auth/2fa/setup - [ ] Create API endpoint: POST /api/auth/2fa/verify - [ ] Create API endpoint: POST /api/auth/2fa/disable - [ ] Generate and store recovery codes - [ ] Modify login endpoint to check 2FA status - [ ] Add unit tests for 2FA logic ## Frontend Tasks - [ ] Create 2FA setup UI component - [ ] Display QR code for authenticator apps - [ ] Create 2FA verification input - [ ] Add 2FA settings page - [ ] Show recovery codes after setup - [ ] Update login flow to handle 2FA - [ ] Add loading states and error handling ## Documentation - [ ] Update API documentation - [ ] Create user guide for 2FA setup
# Authentication Specification (Delta) ## ADDED Requirements ### Requirement: Two-Factor Authentication Setup #### Scenario: User enables 2FA GIVEN a logged-in user without 2FA enabled WHEN they navigate to security settings AND request to enable two-factor authentication THEN the system SHALL generate a TOTP secret AND display a QR code for authenticator apps AND show a manual entry key AND generate 10 recovery codes AND require successful verification before activation ### Requirement: 2FA Verification During Login #### Scenario: User with 2FA enabled logs in GIVEN a user with 2FA enabled WHEN they provide correct email and password THEN the system SHALL prompt for 2FA code AND accept valid TOTP codes AND accept valid recovery codes AND grant access only after successful verification ## MODIFIED Requirements ### Requirement: User Login #### Scenario: User logs in with valid credentials GIVEN a user with registered credentials WHEN they provide correct email and password AND provide 2FA code if 2FA is enabled THEN the system SHALL authenticate the user AND issue a JWT token AND redirect to dashboard
$ openspec list
Active Changes: ┌─────────────────────────┬──────────────────┬─────────────┐ │ Change Name │ Affected Specs │ Tasks │ ├─────────────────────────┼──────────────────┼─────────────┤ │ add-2fa-authentication │ auth/spec.md │ 0/15 done │ └─────────────────────────┴──────────────────┴─────────────┘
$ openspec show add-2fa-authentication
$ openspec validate add-2fa-authentication
✓ proposal.md: Valid ✓ tasks.md: Valid format ✓ specs/auth/spec.md: Valid delta format - Found 2 ADDED requirements - Found 1 MODIFIED requirement - All scenarios properly formatted
$ openspec list
Active Changes: ┌─────────────────────────┬──────────────────┬─────────────┐ │ Change Name │ Affected Specs │ Tasks │ ├─────────────────────────┼──────────────────┼─────────────┤ │ add-2fa-authentication │ auth/spec.md │ 12/17 done │ └─────────────────────────┴──────────────────┴─────────────┘
$ npm test
✓ Auth: 2FA setup generates valid secret (45ms) ✓ Auth: 2FA verification accepts valid codes (123ms) ✓ Auth: Login with 2FA enabled requires code (89ms) ✓ Auth: Recovery codes work correctly (67ms) ✓ Auth: Remember device skips 2FA (95ms) ✓ Auth: All existing auth tests still pass (234ms) Test Suites: 3 passed, 3 total Tests: 24 passed, 24 total
$ openspec archive add-2fa-authentication --yes
Archiving change: add-2fa-authentication ✓ Validated all tasks completed ✓ Merging delta to openspec/specs/auth/spec.md - Added 3 new requirements - Modified 1 existing requirement ✓ Moving to archive: openspec/archive/add-2fa-authentication/ ✓ Updated archive index Archive complete! The source spec has been updated.
openspec/
├── specs/
│ └── auth/
│ └── spec.md # ✨ 已更新，包含 2FA 规范
├── changes/ # 空（变更已归档）
└── archive/
└── add-2fa-authentication/ # 📦 已归档
├── proposal.md
├── tasks.md
├── design.md
└── specs/...
openspec view 在团队会议中展示规范openspec update 获取最新的 AI 指令