feat: 初始化项目，添加 OpenSpec 子模块和 fast-drive 自定义 schema
This commit is contained in:
32
.gitattributes
vendored
Normal file
32
.gitattributes
vendored
Normal file
@@ -0,0 +1,32 @@
|
|||||||
|
# 跨平台行尾规范
|
||||||
|
# 所有文本文件统一用 LF（Unix 风格），避免 CRLF/LF 混用
|
||||||
|
* text=auto eol=lf
|
||||||
|
|
||||||
|
# 二进制文件不转换行尾
|
||||||
|
*.png binary
|
||||||
|
*.jpg binary
|
||||||
|
*.jpeg binary
|
||||||
|
*.gif binary
|
||||||
|
*.ico binary
|
||||||
|
*.svg binary
|
||||||
|
*.pdf binary
|
||||||
|
*.zip binary
|
||||||
|
*.gz binary
|
||||||
|
*.tar binary
|
||||||
|
*.woff binary
|
||||||
|
*.woff2 binary
|
||||||
|
*.ttf binary
|
||||||
|
*.eot binary
|
||||||
|
*.mp4 binary
|
||||||
|
*.mov binary
|
||||||
|
*.mp3 binary
|
||||||
|
|
||||||
|
# Shell 脚本必须 LF
|
||||||
|
*.sh text eol=lf
|
||||||
|
|
||||||
|
# Windows 批处理必须 CRLF
|
||||||
|
*.bat text eol=crlf
|
||||||
|
*.cmd text eol=crlf
|
||||||
|
|
||||||
|
# 锁定文件（如 package-lock.json）保持 LF
|
||||||
|
*.lock text eol=lf
|
||||||
412
.gitignore
vendored
Normal file
412
.gitignore
vendored
Normal file
@@ -0,0 +1,412 @@
|
|||||||
|
### Git.gitignore ###
|
||||||
|
# Created by git for backups. To disable backups in Git:
|
||||||
|
# $ git config --global mergetool.keepBackup false
|
||||||
|
*.orig
|
||||||
|
|
||||||
|
# Created by git when using merge tools for conflicts
|
||||||
|
*.BACKUP.*
|
||||||
|
*.BASE.*
|
||||||
|
*.LOCAL.*
|
||||||
|
*.REMOTE.*
|
||||||
|
*_BACKUP_*.txt
|
||||||
|
*_BASE_*.txt
|
||||||
|
*_LOCAL_*.txt
|
||||||
|
*_REMOTE_*.txt
|
||||||
|
|
||||||
|
### Go.gitignore ###
|
||||||
|
# Binaries for programs and plugins
|
||||||
|
*.exe
|
||||||
|
*.exe~
|
||||||
|
*.dll
|
||||||
|
*.so
|
||||||
|
*.dylib
|
||||||
|
|
||||||
|
# Test binary, built with `go test -c`
|
||||||
|
*.test
|
||||||
|
|
||||||
|
# Output of the go coverage tool, specifically when used with LiteIDE
|
||||||
|
*.out
|
||||||
|
|
||||||
|
# Dependency directories (remove the comment below to include it)
|
||||||
|
# vendor/
|
||||||
|
|
||||||
|
### Go.patch ###
|
||||||
|
/vendor/
|
||||||
|
/Godeps/
|
||||||
|
|
||||||
|
### JetBrains+all.gitignore ###
|
||||||
|
# Covers JetBrains IDEs: IntelliJ, RubyMine, PhpStorm, AppCode, PyCharm, CLion, Android Studio, WebStorm and Rider
|
||||||
|
# Reference: https://intellij-support.jetbrains.com/hc/en-us/articles/206544839
|
||||||
|
|
||||||
|
# User-specific stuff
|
||||||
|
.idea/**/workspace.xml
|
||||||
|
.idea/**/tasks.xml
|
||||||
|
.idea/**/usage.statistics.xml
|
||||||
|
.idea/**/dictionaries
|
||||||
|
.idea/**/shelf
|
||||||
|
|
||||||
|
# Generated files
|
||||||
|
.idea/**/contentModel.xml
|
||||||
|
|
||||||
|
# Sensitive or high-churn files
|
||||||
|
.idea/**/dataSources/
|
||||||
|
.idea/**/dataSources.ids
|
||||||
|
.idea/**/dataSources.local.xml
|
||||||
|
.idea/**/sqlDataSources.xml
|
||||||
|
.idea/**/dynamic.xml
|
||||||
|
.idea/**/uiDesigner.xml
|
||||||
|
.idea/**/dbnavigator.xml
|
||||||
|
|
||||||
|
# Gradle
|
||||||
|
.idea/**/gradle.xml
|
||||||
|
.idea/**/libraries
|
||||||
|
|
||||||
|
# Gradle and Maven with auto-import
|
||||||
|
# When using Gradle or Maven with auto-import, you should exclude module files,
|
||||||
|
# since they will be recreated, and may cause churn. Uncomment if using
|
||||||
|
# auto-import.
|
||||||
|
# .idea/artifacts
|
||||||
|
# .idea/compiler.xml
|
||||||
|
# .idea/jarRepositories.xml
|
||||||
|
# .idea/modules.xml
|
||||||
|
# .idea/*.iml
|
||||||
|
# .idea/modules
|
||||||
|
# *.iml
|
||||||
|
# *.ipr
|
||||||
|
|
||||||
|
# CMake
|
||||||
|
cmake-build-*/
|
||||||
|
|
||||||
|
# Mongo Explorer plugin
|
||||||
|
.idea/**/mongoSettings.xml
|
||||||
|
|
||||||
|
# File-based project format
|
||||||
|
*.iws
|
||||||
|
|
||||||
|
# IntelliJ
|
||||||
|
out/
|
||||||
|
|
||||||
|
# mpeltonen/sbt-idea plugin
|
||||||
|
.idea_modules/
|
||||||
|
|
||||||
|
# JIRA plugin
|
||||||
|
atlassian-ide-plugin.xml
|
||||||
|
|
||||||
|
# Cursive Clojure plugin
|
||||||
|
.idea/replstate.xml
|
||||||
|
|
||||||
|
# Crashlytics plugin (for Android Studio and IntelliJ)
|
||||||
|
com_crashlytics_export_strings.xml
|
||||||
|
crashlytics.properties
|
||||||
|
crashlytics-build.properties
|
||||||
|
fabric.properties
|
||||||
|
|
||||||
|
# Editor-based Rest Client
|
||||||
|
.idea/httpRequests
|
||||||
|
|
||||||
|
# Android studio 3.1+ serialized cache file
|
||||||
|
.idea/caches/build_file_checksums.ser
|
||||||
|
|
||||||
|
### JetBrains+all.patch ###
|
||||||
|
# Ignores the whole .idea folder and all .iml files
|
||||||
|
# See https://github.com/joeblau/gitignore.io/issues/186 and https://github.com/joeblau/gitignore.io/issues/360
|
||||||
|
|
||||||
|
.idea/
|
||||||
|
|
||||||
|
# Reason: https://github.com/joeblau/gitignore.io/issues/186#issuecomment-249601023
|
||||||
|
|
||||||
|
*.iml
|
||||||
|
modules.xml
|
||||||
|
.idea/misc.xml
|
||||||
|
*.ipr
|
||||||
|
|
||||||
|
# Sonarlint plugin
|
||||||
|
.idea/sonarlint
|
||||||
|
|
||||||
|
### Linux.gitignore ###
|
||||||
|
*~
|
||||||
|
|
||||||
|
# temporary files which can be created if a process still has a handle open of a deleted file
|
||||||
|
.fuse_hidden*
|
||||||
|
|
||||||
|
# KDE directory preferences
|
||||||
|
.directory
|
||||||
|
|
||||||
|
# Linux trash folder which might appear on any partition or disk
|
||||||
|
.Trash-*
|
||||||
|
|
||||||
|
# .nfs files are created when an open file is removed but is still being accessed
|
||||||
|
.nfs*
|
||||||
|
|
||||||
|
### Node.gitignore ###
|
||||||
|
# Logs
|
||||||
|
logs
|
||||||
|
*.log
|
||||||
|
npm-debug.log*
|
||||||
|
yarn-debug.log*
|
||||||
|
yarn-error.log*
|
||||||
|
lerna-debug.log*
|
||||||
|
|
||||||
|
# Diagnostic reports (https://nodejs.org/api/report.html)
|
||||||
|
report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
|
||||||
|
|
||||||
|
# Runtime data
|
||||||
|
pids
|
||||||
|
*.pid
|
||||||
|
*.seed
|
||||||
|
*.pid.lock
|
||||||
|
|
||||||
|
# Directory for instrumented libs generated by jscoverage/JSCover
|
||||||
|
lib-cov
|
||||||
|
|
||||||
|
# Coverage directory used by tools like istanbul
|
||||||
|
coverage
|
||||||
|
*.lcov
|
||||||
|
|
||||||
|
# nyc test coverage
|
||||||
|
.nyc_output
|
||||||
|
|
||||||
|
# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
|
||||||
|
.grunt
|
||||||
|
|
||||||
|
# Bower dependency directory (https://bower.io/)
|
||||||
|
bower_components
|
||||||
|
|
||||||
|
# node-waf configuration
|
||||||
|
.lock-wscript
|
||||||
|
|
||||||
|
# Compiled binary addons (https://nodejs.org/api/addons.html)
|
||||||
|
build/Release
|
||||||
|
|
||||||
|
# Dependency directories
|
||||||
|
node_modules/
|
||||||
|
jspm_packages/
|
||||||
|
|
||||||
|
# Test
|
||||||
|
playwright-report
|
||||||
|
test-results
|
||||||
|
|
||||||
|
# TypeScript v1 declaration files
|
||||||
|
typings/
|
||||||
|
|
||||||
|
# TypeScript cache
|
||||||
|
*.tsbuildinfo
|
||||||
|
|
||||||
|
# Optional npm cache directory
|
||||||
|
.npm
|
||||||
|
|
||||||
|
# Optional eslint cache
|
||||||
|
.eslintcache
|
||||||
|
|
||||||
|
# Microbundle cache
|
||||||
|
.rpt2_cache/
|
||||||
|
.rts2_cache_cjs/
|
||||||
|
.rts2_cache_es/
|
||||||
|
.rts2_cache_umd/
|
||||||
|
|
||||||
|
# Optional REPL history
|
||||||
|
.node_repl_history
|
||||||
|
|
||||||
|
# Output of 'npm pack'
|
||||||
|
*.tgz
|
||||||
|
|
||||||
|
# Yarn Integrity file
|
||||||
|
.yarn-integrity
|
||||||
|
|
||||||
|
# dotenv environment variables file
|
||||||
|
.env
|
||||||
|
.env.test
|
||||||
|
|
||||||
|
# parcel-bundler cache (https://parceljs.org/)
|
||||||
|
.cache
|
||||||
|
|
||||||
|
# Next.js build output
|
||||||
|
.next
|
||||||
|
|
||||||
|
# Nuxt.js build / generate output
|
||||||
|
.nuxt
|
||||||
|
dist
|
||||||
|
|
||||||
|
# Gatsby files
|
||||||
|
.cache/
|
||||||
|
# Comment in the public line in if your project uses Gatsby and not Next.js
|
||||||
|
# https://nextjs.org/blog/next-9-1#public-directory-support
|
||||||
|
# public
|
||||||
|
|
||||||
|
# vuepress build output
|
||||||
|
.vuepress/dist
|
||||||
|
|
||||||
|
# Serverless directories
|
||||||
|
.serverless/
|
||||||
|
|
||||||
|
# FuseBox cache
|
||||||
|
.fusebox/
|
||||||
|
|
||||||
|
# DynamoDB Local files
|
||||||
|
.dynamodb/
|
||||||
|
|
||||||
|
# TernJS port file
|
||||||
|
.tern-port
|
||||||
|
|
||||||
|
# Stores VSCode versions used for testing VSCode extensions
|
||||||
|
.vscode-test
|
||||||
|
|
||||||
|
### VisualStudioCode.gitignore ###
|
||||||
|
.vscode/*
|
||||||
|
!.vscode/settings.json
|
||||||
|
!.vscode/tasks.json
|
||||||
|
!.vscode/launch.json
|
||||||
|
!.vscode/extensions.json
|
||||||
|
*.code-workspace
|
||||||
|
|
||||||
|
### VisualStudioCode.patch ###
|
||||||
|
# Ignore all local history of files
|
||||||
|
.history
|
||||||
|
|
||||||
|
### Windows.gitignore ###
|
||||||
|
# Windows thumbnail cache files
|
||||||
|
Thumbs.db
|
||||||
|
Thumbs.db:encryptable
|
||||||
|
ehthumbs.db
|
||||||
|
ehthumbs_vista.db
|
||||||
|
|
||||||
|
# Dump file
|
||||||
|
*.stackdump
|
||||||
|
|
||||||
|
# Folder config file
|
||||||
|
[Dd]esktop.ini
|
||||||
|
|
||||||
|
# Recycle Bin used on file shares
|
||||||
|
$RECYCLE.BIN/
|
||||||
|
|
||||||
|
# Windows Installer files
|
||||||
|
*.cab
|
||||||
|
*.msi
|
||||||
|
*.msix
|
||||||
|
*.msm
|
||||||
|
*.msp
|
||||||
|
|
||||||
|
# Windows shortcuts
|
||||||
|
*.lnk
|
||||||
|
|
||||||
|
### macOS.gitignore ###
|
||||||
|
# General
|
||||||
|
.DS_Store
|
||||||
|
.AppleDouble
|
||||||
|
.LSOverride
|
||||||
|
|
||||||
|
# Icon must end with two \r
|
||||||
|
Icon
|
||||||
|
|
||||||
|
# Thumbnails
|
||||||
|
._*
|
||||||
|
|
||||||
|
# Files that might appear in the root of a volume
|
||||||
|
.DocumentRevisions-V100
|
||||||
|
.fseventsd
|
||||||
|
.Spotlight-V100
|
||||||
|
.TemporaryItems
|
||||||
|
.Trashes
|
||||||
|
.VolumeIcon.icns
|
||||||
|
.com.apple.timemachine.donotpresent
|
||||||
|
|
||||||
|
# Directories potentially created on remote AFP share
|
||||||
|
.AppleDB
|
||||||
|
.AppleDesktop
|
||||||
|
Network Trash Folder
|
||||||
|
Temporary Items
|
||||||
|
.apdisk
|
||||||
|
|
||||||
|
### Python.gitignore ###
|
||||||
|
# Byte-compiled / optimized / DLL files
|
||||||
|
__pycache__/
|
||||||
|
*.py[cod]
|
||||||
|
*$py.class
|
||||||
|
|
||||||
|
# C extensions
|
||||||
|
*.so
|
||||||
|
|
||||||
|
# Distribution / packaging
|
||||||
|
.Python
|
||||||
|
build/
|
||||||
|
develop-eggs/
|
||||||
|
dist/
|
||||||
|
downloads/
|
||||||
|
eggs/
|
||||||
|
.eggs/
|
||||||
|
lib/
|
||||||
|
lib64/
|
||||||
|
parts/
|
||||||
|
sdist/
|
||||||
|
var/
|
||||||
|
wheels/
|
||||||
|
*.egg-info/
|
||||||
|
.installed.cfg
|
||||||
|
*.egg
|
||||||
|
|
||||||
|
# PyInstaller
|
||||||
|
*.manifest
|
||||||
|
*.spec
|
||||||
|
|
||||||
|
# Installer logs
|
||||||
|
pip-log.txt
|
||||||
|
pip-delete-this-directory.txt
|
||||||
|
|
||||||
|
# Unit test / coverage reports
|
||||||
|
htmlcov/
|
||||||
|
.tox/
|
||||||
|
.nox/
|
||||||
|
.coverage
|
||||||
|
.coverage.*
|
||||||
|
nosetests.xml
|
||||||
|
coverage.xml
|
||||||
|
*.cover
|
||||||
|
*.py,cover
|
||||||
|
.hypothesis/
|
||||||
|
.pytest_cache/
|
||||||
|
|
||||||
|
# Translations
|
||||||
|
*.mo
|
||||||
|
*.pot
|
||||||
|
|
||||||
|
# Environments
|
||||||
|
.venv/
|
||||||
|
venv/
|
||||||
|
ENV/
|
||||||
|
env/
|
||||||
|
.python-version
|
||||||
|
|
||||||
|
# Spyder project settings
|
||||||
|
.spyderproject
|
||||||
|
.spyproject
|
||||||
|
|
||||||
|
# Rope project settings
|
||||||
|
.ropeproject
|
||||||
|
|
||||||
|
# mkdocs documentation
|
||||||
|
/site
|
||||||
|
|
||||||
|
# mypy
|
||||||
|
.mypy_cache/
|
||||||
|
|
||||||
|
# Pyre
|
||||||
|
.pyre/
|
||||||
|
|
||||||
|
# pytype
|
||||||
|
.pytype/
|
||||||
|
|
||||||
|
# Cython debug symbols
|
||||||
|
cython_debug/
|
||||||
|
|
||||||
|
# Custom
|
||||||
|
.opencode
|
||||||
|
.claude
|
||||||
|
.codex
|
||||||
|
.pi
|
||||||
|
.agents
|
||||||
|
.worktrees
|
||||||
|
temp
|
||||||
|
|
||||||
|
# Bun
|
||||||
|
.build/
|
||||||
|
*.bun-build
|
||||||
3
.gitmodules
vendored
Normal file
3
.gitmodules
vendored
Normal file
@@ -0,0 +1,3 @@
|
|||||||
|
[submodule "OpenSpec"]
|
||||||
|
path = OpenSpec
|
||||||
|
url = https://github.com/Fission-AI/OpenSpec.git
|
||||||
1
OpenSpec
Submodule
1
OpenSpec
Submodule
Submodule OpenSpec added at 1b06fddd59
80
README.md
Normal file
80
README.md
Normal file
@@ -0,0 +1,80 @@
|
|||||||
|
# OpenSpec Schema
|
||||||
|
|
||||||
|
当前项目用于开发 OpenSpec 工具的自定义 schema 流程。
|
||||||
|
|
||||||
|
## 项目结构
|
||||||
|
|
||||||
|
```
|
||||||
|
openspec-schema/
|
||||||
|
├── OpenSpec/ # OpenSpec 工具源码（Git 子模块）
|
||||||
|
├── fast-drive/ # 自定义 workflow schema
|
||||||
|
│ ├── schema.yaml # workflow 定义文件
|
||||||
|
│ └── templates/ # artifact 模板
|
||||||
|
│ ├── design.md # 设计文档模板
|
||||||
|
│ └── tasks.md # 任务清单模板
|
||||||
|
├── .gitignore
|
||||||
|
└── .gitattributes
|
||||||
|
```
|
||||||
|
|
||||||
|
## 关于 OpenSpec
|
||||||
|
|
||||||
|
OpenSpec 是一款用于在 AI 编程工具中实践 SDD（Specification-Driven Development）开发流程的工具。工具源码位于 `OpenSpec` 目录下（以 Git 子模块形式引用）。
|
||||||
|
|
||||||
|
## fast-drive Schema
|
||||||
|
|
||||||
|
`fast-drive` 是一个简化版的 OpenSpec workflow，采用 **design → tasks → apply** 的精简流程：
|
||||||
|
|
||||||
|
### 特点
|
||||||
|
|
||||||
|
- **跳过 proposal 和 specs 阶段**：直接从 design.md 开始
|
||||||
|
- **中文支持**：design.md 和 tasks.md 使用中文章节标题和正文
|
||||||
|
- **自包含设计**：design.md 包含所有必要信息，即使跨会话也能继续执行
|
||||||
|
- **结构化任务管理**：tasks.md 使用 checkbox 格式跟踪执行进度
|
||||||
|
|
||||||
|
### 工作流程
|
||||||
|
|
||||||
|
1. **design** - 创建 design.md，记录变更的背景、需求、决策和执行计划
|
||||||
|
2. **tasks** - 从 design.md 派生可执行的任务清单
|
||||||
|
3. **apply** - 按依赖顺序执行任务并标记完成
|
||||||
|
|
||||||
|
### 使用方法
|
||||||
|
|
||||||
|
在 OpenSpec 项目中使用 fast-drive workflow：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 初始化 OpenSpec 项目（如果尚未初始化）
|
||||||
|
openspec init
|
||||||
|
|
||||||
|
# 使用 fast-drive workflow 创建新变更
|
||||||
|
/opsx:propose "your-change-description" --schema fast-drive
|
||||||
|
```
|
||||||
|
|
||||||
|
## 开发说明
|
||||||
|
|
||||||
|
### 添加新的自定义 Schema
|
||||||
|
|
||||||
|
1. 在项目根目录创建新的 schema 目录（如 `my-schema/`）
|
||||||
|
2. 创建 `schema.yaml` 定义 workflow 结构
|
||||||
|
3. 在 `templates/` 目录下添加 artifact 模板
|
||||||
|
4. 参考 `fast-drive/` 的结构和 OpenSpec 的 schema 规范
|
||||||
|
|
||||||
|
### 更新 OpenSpec 子模块
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 更新到最新版本
|
||||||
|
git submodule update --remote OpenSpec
|
||||||
|
|
||||||
|
# 或者进入子模块目录切换到特定版本
|
||||||
|
cd OpenSpec
|
||||||
|
git checkout <version-tag>
|
||||||
|
cd ..
|
||||||
|
```
|
||||||
|
|
||||||
|
## 相关链接
|
||||||
|
|
||||||
|
- [OpenSpec 官方文档](https://github.com/Fission-AI/OpenSpec)
|
||||||
|
- [OpenSpec Schema 规范](https://github.com/Fission-AI/OpenSpec/tree/main/docs/customization.md)
|
||||||
|
|
||||||
|
## License
|
||||||
|
|
||||||
|
MIT
|
||||||
150
fast-drive/schema.yaml
Normal file
150
fast-drive/schema.yaml
Normal file
@@ -0,0 +1,150 @@
|
|||||||
|
name: fast-drive
|
||||||
|
version: 1
|
||||||
|
description: 快速 OpenSpec workflow - design -> tasks -> apply
|
||||||
|
artifacts:
|
||||||
|
- id: design
|
||||||
|
generates: design.md
|
||||||
|
description: 自包含的方案说明和执行计划
|
||||||
|
template: design.md
|
||||||
|
instruction: |
|
||||||
|
创建 design.md，作为本次变更“改什么、为什么改、如何执行”的自包含事实来源。
|
||||||
|
|
||||||
|
本 workflow 不使用 proposal 或 specs artifacts。design.md MUST 保留前序探索和用户讨论中的重要结论，确保后续 apply 阶段即使经历上下文压缩或进入新会话，也能正确继续执行。
|
||||||
|
|
||||||
|
语言规则（强制）：
|
||||||
|
|
||||||
|
- fast-drive 的 design.md 使用中文章节标题和中文正文；仅文件名、OpenSpec 术语、schema 字段名、命令、代码符号和必要技术名词保留英文
|
||||||
|
|
||||||
|
- 最终 design.md 不得残留英文模板句子或英文占位内容，除非该英文是 OpenSpec 术语、文件名、schema 字段名、代码符号、命令或必要技术名词
|
||||||
|
|
||||||
|
面向看不到早期对话的人编写。简单变更保持精炼，但必须包含足够细节让执行无歧义。遇到以下情况时增加细节：
|
||||||
|
|
||||||
|
- 跨多个系统、团队、工作流或 artifacts 的横切变更
|
||||||
|
|
||||||
|
- 新增依赖、集成、供应商、工具、策略或外部输入
|
||||||
|
|
||||||
|
- 重要的信息模型、流程模型、数据模型或归属关系变化
|
||||||
|
|
||||||
|
- 涉及安全、隐私、合规、性能、运维或迁移复杂度
|
||||||
|
|
||||||
|
- 执行前需要先做决策才能降低歧义
|
||||||
|
|
||||||
|
- 前序讨论已经确认非显而易见的需求、约束或被否决方案
|
||||||
|
|
||||||
|
必需章节（建议使用以下中文章节标题）：
|
||||||
|
|
||||||
|
- **背景**：问题、当前状态、相关参考资料，以及触发本次变更的用户请求
|
||||||
|
|
||||||
|
- **讨论记录**：探索或前序讨论中必须保留的关键点，包括已确认结论、用户偏好、约束和重要的被否决方案
|
||||||
|
|
||||||
|
- **需求**：预期结果、行为/流程/接口/内容变化、连续性要求和验收标准
|
||||||
|
|
||||||
|
- **目标 / 非目标**：本次变更要达成的目标，以及明确不在范围内的内容
|
||||||
|
|
||||||
|
- **执行约束**：必须遵守的约束、禁止的做法、需保持的行为/流程、依赖限制，以及项目或 workflow 特有边界
|
||||||
|
|
||||||
|
- **影响范围**：与本次变更相关的具体 artifacts、参考资料、相关方、系统、工作流、文档、配置、资产或交接事项
|
||||||
|
|
||||||
|
- **决策**：关键选择及理由（为什么选 X 而不是 Y）。每个重要决策都要包含考虑过的替代方案，以及未选择它们的原因
|
||||||
|
|
||||||
|
- **执行计划**：主要工作流或待修改 artifacts、集成或交接点、执行顺序，以及必要的发布/落地说明
|
||||||
|
|
||||||
|
- **验证计划**：用于证明变更完成所需的验证检查、审查、批准、验收检查、文档检查、沟通检查和人工检查
|
||||||
|
|
||||||
|
- **风险 / 权衡**：已知限制和可能出错的事项
|
||||||
|
格式：[风险] -> 缓解措施
|
||||||
|
|
||||||
|
- **待解决问题**：执行前仍需解决的决策、假设或未知项。必须区分会阻塞 apply 的问题和非阻塞后续问题。没有未决问题时使用“无”
|
||||||
|
|
||||||
|
可选章节（相关时添加，建议使用中文章节标题）：
|
||||||
|
|
||||||
|
- **迁移 / 发布计划**：发布步骤、沟通安排、归属、回滚或连续性策略
|
||||||
|
|
||||||
|
聚焦保留需求、理由、约束和方案。除非某个细节是讨论中明确做出的决策，否则避免逐行或逐步骤展开。
|
||||||
|
|
||||||
|
优先写可长期使用的摘要，而不是聊天记录转写。当具体 artifact 名称、数据/信息形状、示例、相关方、归属和边界场景会影响执行时，必须写清楚。
|
||||||
|
|
||||||
|
不要在 design.md 使用任务 checkbox；checkbox 只属于 tasks.md。
|
||||||
|
|
||||||
|
最终 design.md 不得包含未解决的模板注释、空表格行或占位文本。
|
||||||
|
|
||||||
|
如果信息缺失，写明假设和待解决问题，不要编造隐藏需求。不要依赖未写入文档的聊天上下文。
|
||||||
|
requires: []
|
||||||
|
- id: tasks
|
||||||
|
generates: tasks.md
|
||||||
|
description: 从 design.md 派生的可跟踪执行清单
|
||||||
|
template: tasks.md
|
||||||
|
instruction: |
|
||||||
|
创建 tasks.md，将 design.md 拆解为可执行工作项。
|
||||||
|
|
||||||
|
**重要：必须遵守以下模板中的 checkbox 行格式。** apply 阶段会解析 checkbox 格式跟踪进度。未使用 `- [ ]` 的任务不会被跟踪。
|
||||||
|
|
||||||
|
语言规则（强制）：
|
||||||
|
|
||||||
|
- fast-drive 的 tasks.md 使用中文分组标题和中文任务描述；仅文件名、OpenSpec 术语、schema 字段名、命令、代码符号和必要技术名词保留英文
|
||||||
|
|
||||||
|
- 每个可跟踪任务必须保留 OpenSpec CLI 可解析的单行 checkbox 格式，例如 `- [ ] 1.1 任务描述` 或 `- [x] 1.1 已完成任务描述`
|
||||||
|
|
||||||
|
- 最终 tasks.md 不得残留英文模板任务或英文占位内容，除非该英文是 OpenSpec 术语、文件名、schema 字段名、代码符号、命令或必要技术名词
|
||||||
|
|
||||||
|
编写规则：
|
||||||
|
|
||||||
|
- 任务必须从 design.md 派生。不要依赖 proposal.md 或 specs artifacts；任何相关前序讨论都必须已经记录在 design.md 中
|
||||||
|
|
||||||
|
- 相关任务按 `##` 编号标题分组，分组标题使用中文
|
||||||
|
|
||||||
|
- 每个任务 MUST 是单行 checkbox：`- [ ] X.Y 任务描述`
|
||||||
|
|
||||||
|
- 任务粒度应足够小，能在一个会话内完成
|
||||||
|
|
||||||
|
- 按依赖顺序排序（先做必须先完成的事项）
|
||||||
|
|
||||||
|
- 当执行依赖执行约束、影响范围或待解决问题时，从上下文审查任务开始
|
||||||
|
|
||||||
|
- 需要时包含验证任务，覆盖检查、审查、批准、验收、文档、沟通和人工检查
|
||||||
|
|
||||||
|
- 除非仓库、版本控制或发布操作明确属于本次变更范围，否则不要包含这类任务
|
||||||
|
|
||||||
|
- 最终 tasks.md 不得包含未解决的模板注释、空表格行或占位任务文本
|
||||||
|
|
||||||
|
示例：
|
||||||
|
|
||||||
|
```
|
||||||
|
## 1. 上下文审查
|
||||||
|
|
||||||
|
- [ ] 1.1 阅读 design.md，识别范围、需求、决策、执行约束和待解决问题
|
||||||
|
- [ ] 1.2 审查“影响范围”中列出的相关 artifacts 和参考资料
|
||||||
|
|
||||||
|
## 2. 执行
|
||||||
|
|
||||||
|
- [ ] 2.1 执行 design.md 中的第一个具体工作项
|
||||||
|
- [ ] 2.2 执行 design.md 中的下一个具体工作项
|
||||||
|
|
||||||
|
## 3. 验证
|
||||||
|
|
||||||
|
- [ ] 3.1 执行“验证计划”中要求的验证
|
||||||
|
- [ ] 3.2 执行项目或 workflow 要求的质量检查
|
||||||
|
- [ ] 3.3 执行“验证计划”中要求的人工审查或验收检查
|
||||||
|
|
||||||
|
## 4. 文档 / 沟通
|
||||||
|
|
||||||
|
- [ ] 4.1 如果行为、流程、接口、配置或使用方式发生变化，更新相关文档、runbook、沟通材料或项目参考资料
|
||||||
|
```
|
||||||
|
|
||||||
|
以 design.md 中的范围、需求、决策、执行方向和验证预期为依据。
|
||||||
|
|
||||||
|
每个任务都应可验证：必须能明确判断任务何时完成。
|
||||||
|
requires:
|
||||||
|
- design
|
||||||
|
apply:
|
||||||
|
requires:
|
||||||
|
- design
|
||||||
|
- tasks
|
||||||
|
tracks: tasks.md
|
||||||
|
instruction: |
|
||||||
|
先阅读 design.md，再阅读 tasks.md。
|
||||||
|
同时遵守 workflow context/configuration，例如存在时读取 openspec/config.yaml，以及 design.md 引用的相关项目或 workflow 文档。
|
||||||
|
将 design.md 视为范围、需求、决策、执行约束、执行方向和验证预期的事实来源。
|
||||||
|
按依赖顺序处理待办任务，并在完成后及时标记。
|
||||||
|
只有任务执行完成且必要验证完成后，才能标记任务完成。
|
||||||
|
如果 tasks 与 design.md 冲突、design.md 存在阻塞性待解决问题，或需要澄清，必须暂停。
|
||||||
77
fast-drive/templates/design.md
Normal file
77
fast-drive/templates/design.md
Normal file
@@ -0,0 +1,77 @@
|
|||||||
|
## 背景
|
||||||
|
|
||||||
|
<!-- 记录问题、当前状态、相关参考资料，以及触发本次变更的用户请求 -->
|
||||||
|
|
||||||
|
## 讨论记录
|
||||||
|
|
||||||
|
<!-- 记录探索或前序讨论中 apply 阶段必须保留的关键结论 -->
|
||||||
|
|
||||||
|
- 已确认结论：
|
||||||
|
- 用户偏好：
|
||||||
|
- 约束：
|
||||||
|
- 被否决方案：
|
||||||
|
|
||||||
|
## 需求
|
||||||
|
|
||||||
|
<!-- 记录预期结果、行为/流程/接口/内容变化、连续性要求和验收标准 -->
|
||||||
|
|
||||||
|
| 需求 | 验收标准 |
|
||||||
|
| ---- | -------- |
|
||||||
|
| | |
|
||||||
|
|
||||||
|
## 目标 / 非目标
|
||||||
|
|
||||||
|
**目标：**
|
||||||
|
<!-- 记录本次 design 要达成的目标 -->
|
||||||
|
|
||||||
|
**非目标：**
|
||||||
|
<!-- 记录明确不在范围内的内容 -->
|
||||||
|
|
||||||
|
## 执行约束
|
||||||
|
|
||||||
|
<!-- 记录必须遵守的约束、禁止的做法、需保持的行为/流程、依赖限制，以及项目或 workflow 特有边界 -->
|
||||||
|
|
||||||
|
- 依赖限制：
|
||||||
|
- 约束：
|
||||||
|
- 质量门禁：
|
||||||
|
- 相关方：
|
||||||
|
- 文档 / 沟通：
|
||||||
|
- 兼容性 / 连续性：
|
||||||
|
|
||||||
|
## 影响范围
|
||||||
|
|
||||||
|
<!-- 记录与本次变更相关的具体 artifacts、参考资料、相关方、系统、工作流、文档、配置、资产或交接事项 -->
|
||||||
|
|
||||||
|
| 范围 | Artifacts / 参考资料 | 预期变更 | 备注 |
|
||||||
|
| ---- | -------------------- | -------- | ---- |
|
||||||
|
| <!-- 范围 --> | <!-- Artifacts / 参考资料 --> | <!-- 预期变更 --> | <!-- 备注 --> |
|
||||||
|
|
||||||
|
## 决策
|
||||||
|
|
||||||
|
<!-- 记录关键决策、理由和考虑过的替代方案 -->
|
||||||
|
|
||||||
|
| 决策 | 理由 | 已否决替代方案 |
|
||||||
|
| ---- | ---- | ---------------- |
|
||||||
|
| | | |
|
||||||
|
|
||||||
|
## 执行计划
|
||||||
|
|
||||||
|
<!-- 记录主要工作流或待修改 artifacts、集成或交接点、执行顺序，以及必要的发布/落地说明 -->
|
||||||
|
|
||||||
|
## 验证计划
|
||||||
|
|
||||||
|
<!-- 记录用于证明变更完成所需的验证检查、审查、批准、验收检查、文档检查、沟通检查和人工检查 -->
|
||||||
|
|
||||||
|
| 需求 / 风险 | 验证方式 |
|
||||||
|
| ----------- | -------- |
|
||||||
|
| | |
|
||||||
|
|
||||||
|
## 风险 / 权衡
|
||||||
|
|
||||||
|
<!-- 格式：[风险] -> 缓解措施 -->
|
||||||
|
|
||||||
|
## 待解决问题
|
||||||
|
|
||||||
|
| 状态 | 问题 | 所需决策 |
|
||||||
|
| ---- | ---- | -------- |
|
||||||
|
| 无 | 无待解决问题。 | 无需决策 |
|
||||||
19
fast-drive/templates/tasks.md
Normal file
19
fast-drive/templates/tasks.md
Normal file
@@ -0,0 +1,19 @@
|
|||||||
|
## 1. 上下文审查
|
||||||
|
|
||||||
|
- [ ] 1.1 阅读 design.md，识别范围、需求、决策、执行约束和待解决问题
|
||||||
|
- [ ] 1.2 审查“影响范围”中列出的相关 artifacts 和参考资料
|
||||||
|
|
||||||
|
## 2. 执行
|
||||||
|
|
||||||
|
- [ ] 2.1 执行 design.md 中的第一个具体工作项
|
||||||
|
- [ ] 2.2 执行 design.md 中的下一个具体工作项
|
||||||
|
|
||||||
|
## 3. 验证
|
||||||
|
|
||||||
|
- [ ] 3.1 执行“验证计划”中要求的验证
|
||||||
|
- [ ] 3.2 执行项目或 workflow 要求的质量检查
|
||||||
|
- [ ] 3.3 执行“验证计划”中要求的人工审查或验收检查
|
||||||
|
|
||||||
|
## 4. 文档 / 沟通
|
||||||
|
|
||||||
|
- [ ] 4.1 如果行为、流程、接口、配置或使用方式发生变化，更新相关文档、runbook、沟通材料或项目参考资料
|
||||||
Reference in New Issue
Block a user