工件 (Artifact)
工件是 OpenSpec 变更中创建的文档。它们共同描述了提议的变更及其实施计划。
工件类型
OpenSpec 支持以下工件类型：
| 工件 | 描述 | 必需 | 说明 |
|---|---|---|---|
proposal.md | 提案，解释为什么和什么 | 是 | 变更的意图和范围 |
specs/ | 增量规范，显示什么变化 | 是 | ADDED/MODIFIED/REMOVED 需求 |
design.md | 设计，解释如何实现 | 是 | 技术方法和架构决策 |
tasks.md | 任务列表，实施清单 | 是 | 待办事项和检查项 |
工件关系
proposal ──► specs ──► design ──► tasks ──► implement
▲ ▲ ▲ │
└───────────┴──────────┴────────────────────┘
update as you learn
你可以随时回到前面的工件，根据学习到的信息进行完善。
工件详细说明
1. 提案 (proposal.md)
提案是变更的起点，解释为什么要做这个变更。
内容
# Proposal: <变更名称>
## Intent
解释变更的意图和目标。
## Scope
描述变更的范围，包括包含和不包含的内容。
## Approach
描述实现变更的方法。
## Dependencies
列出依赖关系（如果有）。
示例
# Proposal: Add Dark Mode
## Intent
Users have requested a dark mode option to reduce eye strain during nighttime usage.
## Scope
This change will add:
- Theme toggle in settings
- System preference detection
- Persistent user preference
This change will NOT:
- Change existing light mode behavior
- Add other theme options
## Approach
1. Use CSS custom properties for theming
2. Implement React context for state management
3. Store preference in localStorage
## Dependencies
- None
2. 增量规范 (specs/)
增量规范显示相对于当前规范的变化。
格式
# Delta for <领域>
## ADDED Requirements
新添加的需求。
## MODIFIED Requirements
修改的需求。
## REMOVED Requirements
删除的需求。
示例
# Delta for UI
## ADDED Requirements
### Requirement: Theme Selection
The system SHALL allow users to choose between light and dark themes.
#### Scenario: Manual toggle
- GIVEN a user on any page
- WHEN the user clicks the theme toggle
- THEN the theme switches immediately
- AND the preference persists across sessions
## MODIFIED Requirements
None
## REMOVED Requirements
None
3. 设计 (design.md)
设计文档解释如何实现变更。
内容
# Design: <变更名称>
## Architecture
总体架构决策。
## Implementation Steps
实施步骤清单。
## API Changes
API 变更（如果有）。
## Testing
测试计划。
示例
# Design: Add Dark Mode
## Architecture
- Use CSS custom properties for theming
- Implement React context for state management
- Use localStorage for persistence
## Implementation Steps
1. Create ThemeContext with light/dark state
2. Add CSS custom properties to globals.css
3. Implement localStorage persistence
4. Create ThemeToggle component
## API Changes
None
## Testing
- Unit tests for ThemeContext
- Integration tests for ThemeToggle
- E2E tests for theme switching
4. 任务 (tasks.md)
任务列表提供实施的 检查清单。
格式
# Tasks
## 领域 1
- [ ] 任务 1.1
- [ ] 任务 1.2
## 领域 2
- [ ] 任务 2.1
- [ ] 任务 2.2
示例
# Tasks
## 1. Theme Infrastructure
- [ ] 1.1 Create ThemeContext with light/dark state
- [ ] 1.2 Add CSS custom properties to globals.css
- [ ] 1.3 Implement localStorage persistence
## 2. UI Components
- [ ] 2.1 Create ThemeToggle component
- [ ] 2.2 Add toggle to settings page
- [ ] 2.3 Update Header to include quick toggle
## 3. Styling
- [ ] 3.1 Define dark theme color palette
- [ ] 3.2 Update components to use CSS variables
## 4. Testing
- [ ] 4.1 Write unit tests
- [ ] 4.2 Write integration tests
工件工作流
默认快速路径
/opsx:propose → 创建所 有必需工件
/opsx:apply → 执行任务
/opsx:archive → 归档变更
扩展工作流
/opsx:new → 创建变更骨架
/opsx:ff → 填充所有工件
/opsx:apply → 执行任务
/opsx:verify → 验证实现
/opsx:archive → 归档变更
工件最佳实践
- 完整 - 确保所有必需工件都已创建
- 具体 - 提供具体、可操作的细节
- 更新 - 根据学习到的信息更新工件
- 一致 - 保持工件之间的信息一致