lanyuanxiaoyao/Alfred
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 中文化 fast-drive 文档模板

Browse Source
This commit is contained in:
兰缘小妖
2026-05-27 18:30:03 +08:00
parent 348b35ef8c
commit be4b85126b
7 changed files with 195 additions and 232 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
openspec/config.yaml
View File

@@ -2,7 +2,6 @@ schema: fast-drive
context: |
- 使用中文（注释、文档、交流），面向中文开发者
- openspec文档的关键字按openspec规范使用，不要翻译为中文
- **优先阅读 docs/README.md** 获取文档路由、归属矩阵和影响分析规则
- **其次阅读 docs/development/README.md** 获取开发规范、常用命令、质量门禁和全局规则
- 文档文件名优先使用单个英文单词（usage.md、config.md、deploy.md、troubleshoot.md），目录上下文足以消歧时不在文件名重复限定词
@@ -29,8 +28,10 @@ context: |
rules:
design:
- fast-drive的design.md章节标题和正文使用中文；仅OpenSpec术语、文件名、schema字段名、命令和代码符号保留英文
- 先前的讨论技术方案要尽可能体现在设计文档中，便于指导实现阶段不偏离已定的技术路线
tasks:
- fast-drive的tasks.md分组标题、任务描述和验证说明使用中文；每个任务必须保留OpenSpec CLI可解析的单行checkbox格式
- 一行一个任务，严禁任务内容跨行
- 如果是代码存在更新必须
- 执行完整的测试、代码检查、格式检查等质量保障手段

189
openspec/schemas/fast-drive/schema.yaml
View File

@@ -1,170 +1,139 @@
name: fast-drive
version: 1
description: Fast OpenSpec workflow - design -> tasks -> apply
description: 快速 OpenSpec workflow - design -> tasks -> apply
artifacts:
- id: design
generates: design.md
description: Self-contained solution brief and execution plan
description: 自包含的方案说明和执行计划
template: design.md
instruction: |
Create design.md as the self-contained source of truth for what will
change, why it is changing, and how the work will be executed.
创建 design.md，作为本次变更“改什么、为什么改、如何执行”的自包含事实来源。
This workflow does not use proposal or specs artifacts. design.md MUST
preserve the important outcomes from prior exploration and user
discussion so a later apply phase can proceed correctly even after
context compression or in a new session.
本 workflow 不使用 proposal 或 specs artifacts。design.md MUST 保留前序探索和用户讨论中的重要结论，确保后续 apply 阶段即使经历上下文压缩或进入新会话，也能正确继续执行。
Write for someone who cannot see the earlier conversation. Keep simple
changes concise, but include enough detail to make execution
unambiguous. Add more detail when any apply:
语言规则（强制）：
- Cross-cutting change across multiple systems, teams, workstreams, or
artifacts
- fast-drive 的 design.md 使用中文章节标题和中文正文；仅文件名、OpenSpec 术语、schema 字段名、命令、代码符号和必要技术名词保留英文
- New dependency, integration, vendor, tool, policy, or external input
- 最终 design.md 不得残留英文模板句子或英文占位内容，除非该英文是 OpenSpec 术语、文件名、schema 字段名、代码符号、命令或必要技术名词
- Significant information model, process model, data model, or ownership
changes
面向看不到早期对话的人编写。简单变更保持精炼，但必须包含足够细节让执行无歧义。遇到以下情况时增加细节：
- Security, privacy, compliance, performance, operational, or migration
complexity
- 跨多个系统、团队、工作流或 artifacts 的横切变更
- Ambiguity that benefits from decisions before execution
- 新增依赖、集成、供应商、工具、策略或外部输入
- Prior discussion settled non-obvious requirements, constraints, or
rejected alternatives
- 重要的信息模型、流程模型、数据模型或归属关系变化
Required sections:
- 涉及安全、隐私、合规、性能、运维或迁移复杂度
- **Context**: Problem, current state, relevant references, and the user
request that triggered this change
- 执行前需要先做决策才能降低歧义
- **Discussion Notes**: Key points from exploration or prior discussion
that must not be lost. Include agreed conclusions, user preferences,
constraints, and important rejected ideas.
- 前序讨论已经确认非显而易见的需求、约束或被否决方案
- **Requirements**: Expected outcomes, behavior/process/interface/content
changes, continuity expectations, and acceptance criteria.
必需章节（建议使用以下中文章节标题）：
- **Goals / Non-Goals**: What this change will achieve and what is
explicitly out of scope.
- **背景**：问题、当前状态、相关参考资料，以及触发本次变更的用户请求
- **Execution Guardrails**: Must-follow constraints, forbidden approaches,
preserved behavior/processes, dependency limits, and project- or
workflow-specific boundaries.
- **讨论记录**：探索或前序讨论中必须保留的关键点，包括已确认结论、用户偏好、约束和重要的被否决方案
- **Affected Areas**: Concrete artifacts, references, stakeholders,
systems, workstreams, documents, configurations, assets, or handoffs that
are relevant to the change.
- **需求**：预期结果、行为/流程/接口/内容变化、连续性要求和验收标准
- **Decisions**: Key choices with rationale (why X over Y?). For each
important decision, include alternatives considered and why they were not
chosen.
- **目标 / 非目标**：本次变更要达成的目标，以及明确不在范围内的内容
- **Execution Plan**: Main workstreams or artifacts to change, integration
or handoff points, sequencing, and any rollout notes.
- **执行约束**：必须遵守的约束、禁止的做法、需保持的行为/流程、依赖限制，以及项目或 workflow 特有边界
- **Verification Plan**: Validation checks, reviews, approvals,
acceptance checks, documentation checks, communication checks, and manual
checks needed to prove the change is complete.
- **影响范围**：与本次变更相关的具体 artifacts、参考资料、相关方、系统、工作流、文档、配置、资产或交接事项
- **Risks / Trade-offs**: Known limitations and things that could go
wrong.
Format: [Risk] -> Mitigation
- **决策**：关键选择及理由（为什么选 X 而不是 Y）。每个重要决策都要包含考虑过的替代方案，以及未选择它们的原因
- **Open Questions**: Outstanding decisions, assumptions, or unknowns to
resolve before execution. Separate blocking questions that must pause
apply from non-blocking follow-ups. Use "None" if there are no open
questions.
- **执行计划**：主要工作流或待修改 artifacts、集成或交接点、执行顺序，以及必要的发布/落地说明
Optional sections when relevant:
- **验证计划**：用于证明变更完成所需的验证检查、审查、批准、验收检查、文档检查、沟通检查和人工检查
- **Migration / Rollout Plan**: Rollout steps, communication, ownership,
rollback, or continuity strategy.
- **风险 / 权衡**：已知限制和可能出错的事项
格式：[风险] -> 缓解措施
Focus on preserving requirements, rationale, constraints, and approach.
Avoid line-by-line or step-by-step details unless a detail is a deliberate
decision from the discussion.
- **待解决问题**：执行前仍需解决的决策、假设或未知项。必须区分会阻塞 apply 的问题和非阻塞后续问题。没有未决问题时使用“无”
Prefer durable summaries over chat transcripts. Use concrete artifact
names, data/information shapes, examples, stakeholders, ownership, and
edge cases when they affect execution.
可选章节（相关时添加，建议使用中文章节标题）：
Do not use task checkboxes in design.md; checkboxes belong only in
tasks.md.
- **迁移 / 发布计划**：发布步骤、沟通安排、归属、回滚或连续性策略
Final design.md must not contain unresolved template comments, empty
table rows, or placeholder text.
聚焦保留需求、理由、约束和方案。除非某个细节是讨论中明确做出的决策，否则避免逐行或逐步骤展开。
If information is missing, state assumptions and open questions instead
of inventing hidden requirements. Do not rely on unstated chat context.
优先写可长期使用的摘要，而不是聊天记录转写。当具体 artifact 名称、数据/信息形状、示例、相关方、归属和边界场景会影响执行时，必须写清楚。
不要在 design.md 使用任务 checkbox；checkbox 只属于 tasks.md。
最终 design.md 不得包含未解决的模板注释、空表格行或占位文本。
如果信息缺失，写明假设和待解决问题，不要编造隐藏需求。不要依赖未写入文档的聊天上下文。
requires: []
- id: tasks
generates: tasks.md
description: Trackable execution checklist derived from design.md
description: 从 design.md 派生的可跟踪执行清单
template: tasks.md
instruction: |
Create tasks.md by breaking design.md into executable work.
创建 tasks.md，将 design.md 拆解为可执行工作项。
**IMPORTANT: Follow the template below exactly.** The apply phase parses
checkbox format to track progress. Tasks not using `- [ ]` will not be
tracked.
**重要：必须遵守以下模板中的 checkbox 行格式。** apply 阶段会解析 checkbox 格式跟踪进度。未使用 `- [ ]` 的任务不会被跟踪。
Guidelines:
语言规则（强制）：
- Derive tasks from design.md. Do not depend on proposal.md or specs
artifacts; any relevant prior discussion must already be captured in
design.md.
- fast-drive 的 tasks.md 使用中文分组标题和中文任务描述；仅文件名、OpenSpec 术语、schema 字段名、命令、代码符号和必要技术名词保留英文
- Group related tasks under `##` numbered headings
- 每个可跟踪任务必须保留 OpenSpec CLI 可解析的单行 checkbox 格式，例如 `- [ ] 1.1 任务描述` 或 `- [x] 1.1 已完成任务描述`
- Each task MUST be a single-line checkbox: `- [ ] X.Y Task description`
- 最终 tasks.md 不得残留英文模板任务或英文占位内容，除非该英文是 OpenSpec 术语、文件名、schema 字段名、代码符号、命令或必要技术名词
- Tasks should be small enough to complete in one session
编写规则：
- Order tasks by dependency (what must be done first?)
- 任务必须从 design.md 派生。不要依赖 proposal.md 或 specs artifacts；任何相关前序讨论都必须已经记录在 design.md 中
- Start with context review tasks when execution depends on guardrails,
affected areas, or open questions
- 相关任务按 `##` 编号标题分组，分组标题使用中文
- Include validation tasks for checks, reviews, approvals, acceptance,
documentation, communication, and manual checks when required
- 每个任务 MUST 是单行 checkbox：`- [ ] X.Y 任务描述`
- Do not include repository, version-control, or release operation tasks
unless they are explicitly part of the change scope
- 任务粒度应足够小，能在一个会话内完成
- Final tasks.md must not contain unresolved template comments, empty
table rows, or placeholder task text
- 按依赖顺序排序（先做必须先完成的事项）
Example:
- 当执行依赖执行约束、影响范围或待解决问题时，从上下文审查任务开始
- 需要时包含验证任务，覆盖检查、审查、批准、验收、文档、沟通和人工检查
- 除非仓库、版本控制或发布操作明确属于本次变更范围，否则不要包含这类任务
- 最终 tasks.md 不得包含未解决的模板注释、空表格行或占位任务文本
示例：
```
## 1. Context Review
## 1. 上下文审查
- [ ] 1.1 Read design.md and identify scope, requirements, decisions, guardrails, and open questions
- [ ] 1.2 Review relevant artifacts and references listed in Affected Areas
- [ ] 1.1 阅读 design.md，识别范围、需求、决策、执行约束和待解决问题
- [ ] 1.2 审查“影响范围”中列出的相关 artifacts 和参考资料
## 2. Execution
## 2. 执行
- [ ] 2.1 Execute first concrete work item from design.md
- [ ] 2.2 Execute next concrete work item from design.md
- [ ] 2.1 执行 design.md 中的第一个具体工作项
- [ ] 2.2 执行 design.md 中的下一个具体工作项
## 3. Validation
## 3. 验证
- [ ] 3.1 Run required validation from Verification Plan
- [ ] 3.2 Perform quality checks required by the project or workflow
- [ ] 3.3 Perform required manual review or acceptance checks from Verification Plan
- [ ] 3.1 执行“验证计划”中要求的验证
- [ ] 3.2 执行项目或 workflow 要求的质量检查
- [ ] 3.3 执行“验证计划”中要求的人工审查或验收检查
## 4. Documentation / Communication
## 4. 文档 / 沟通
- [ ] 4.1 Update relevant documentation, runbooks, communication materials, or project references if behavior, process, interface, configuration, or usage changed
- [ ] 4.1 如果行为、流程、接口、配置或使用方式发生变化，更新相关文档、runbook、沟通材料或项目参考资料
```
Reference design.md for scope, requirements, decisions, execution
direction, and verification expectations.
以 design.md 中的范围、需求、决策、执行方向和验证预期为依据。
Each task should be verifiable: it must be clear when the task is done.
每个任务都应可验证：必须能明确判断任务何时完成。
requires:
- design
apply:
@@ -173,9 +142,9 @@ apply:
- tasks
tracks: tasks.md
instruction: |
Read design.md first, then tasks.md.
Also follow workflow context/configuration, such as openspec/config.yaml when available, and any relevant project or workflow documentation referenced by design.md.
Treat design.md as the source of truth for scope, requirements, decisions, guardrails, execution direction, and verification expectations.
Work through pending tasks in dependency order and mark complete as you go.
Mark a task complete only after its execution and required verification are done.
Pause if tasks conflict with design.md, if design.md has blocking open questions, or if clarification is needed.
先阅读 design.md，再阅读 tasks.md。
同时遵守 workflow context/configuration，例如存在时读取 openspec/config.yaml，以及 design.md 引用的相关项目或 workflow 文档。
将 design.md 视为范围、需求、决策、执行约束、执行方向和验证预期的事实来源。
按依赖顺序处理待办任务，并在完成后及时标记。
只有任务执行完成且必要验证完成后，才能标记任务完成。
如果 tasks 与 design.md 冲突、design.md 存在阻塞性待解决问题，或需要澄清，必须暂停。

92
openspec/schemas/fast-drive/templates/design.md
View File

@@ -1,77 +1,77 @@
## Context
## 背景
<!-- Problem, current state, relevant references, and triggering user request -->
<!-- 记录问题、当前状态、相关参考资料，以及触发本次变更的用户请求 -->
## Discussion Notes
## 讨论记录
<!-- Key conclusions from exploration or prior discussion that apply must preserve -->
<!-- 记录探索或前序讨论中 apply 阶段必须保留的关键结论 -->
- Agreed conclusions:
- User preferences:
- Constraints:
- Rejected ideas:
- 已确认结论：
- 用户偏好：
- 约束：
- 被否决方案：
## Requirements
## 需求
<!-- Expected outcomes, behavior/process/interface/content changes, continuity expectations, and acceptance criteria -->
<!-- 记录预期结果、行为/流程/接口/内容变化、连续性要求和验收标准 -->
| Requirement | Acceptance Criteria |
| ----------- | ------------------- |
| 需求 | 验收标准 |
| ---- | -------- |
| | |
## Goals / Non-Goals
## 目标 / 非目标
**Goals:**
<!-- What this design aims to achieve -->
**目标：**
<!-- 记录本次 design 要达成的目标 -->
**Non-Goals:**
<!-- What is explicitly out of scope -->
**非目标：**
<!-- 记录明确不在范围内的内容 -->
## Execution Guardrails
## 执行约束
<!-- Must-follow constraints, forbidden approaches, preserved behavior/processes, dependency limits, and project- or workflow-specific boundaries -->
<!-- 记录必须遵守的约束、禁止的做法、需保持的行为/流程、依赖限制，以及项目或 workflow 特有边界 -->
- Dependencies:
- Constraints:
- Quality Bar:
- Stakeholders:
- Documentation / Communication:
- Compatibility / Continuity:
- 依赖限制：
- 约束：
- 质量门禁：
- 相关方：
- 文档 / 沟通：
- 兼容性 / 连续性：
## Affected Areas
## 影响范围
<!-- Concrete artifacts, references, stakeholders, systems, workstreams, documents, configurations, assets, or handoffs relevant to this change -->
<!-- 记录与本次变更相关的具体 artifacts、参考资料、相关方、系统、工作流、文档、配置、资产或交接事项 -->
| Area | Artifacts / References | Expected Change | Notes |
| ---- | ---------------------- | --------------- | ----- |
| <!-- Area --> | <!-- Artifacts / References --> | <!-- Expected Change --> | <!-- Notes --> |
| 范围 | Artifacts / 参考资料 | 预期变更 | 备注 |
| ---- | -------------------- | -------- | ---- |
| <!-- 范围 --> | <!-- Artifacts / 参考资料 --> | <!-- 预期变更 --> | <!-- 备注 --> |
## Decisions
## 决策
<!-- Key decisions, rationale, and alternatives considered -->
<!-- 记录关键决策、理由和考虑过的替代方案 -->
| Decision | Rationale | Alternatives Rejected |
| -------- | --------- | --------------------- |
| 决策 | 理由 | 已否决替代方案 |
| ---- | ---- | ---------------- |
| | | |
## Execution Plan
## 执行计划
<!-- Main workstreams or artifacts to change, integration or handoff points, sequencing, and rollout notes -->
<!-- 记录主要工作流或待修改 artifacts、集成或交接点、执行顺序，以及必要的发布/落地说明 -->
## Verification Plan
## 验证计划
<!-- Validation checks, reviews, approvals, acceptance checks, documentation checks, communication checks, and manual checks needed -->
<!-- 记录用于证明变更完成所需的验证检查、审查、批准、验收检查、文档检查、沟通检查和人工检查 -->
| Requirement / Risk | Verification |
| ------------------ | ------------ |
| 需求 / 风险 | 验证方式 |
| ----------- | -------- |
| | |
## Risks / Trade-offs
## 风险 / 权衡
<!-- Format: [Risk] -> Mitigation -->
<!-- 格式：[风险] -> 缓解措施 -->
## Open Questions
## 待解决问题
| Status | Question | Decision Needed |
| ------ | -------- | --------------- |
| None | No open questions. | None |
| 状态 | 问题 | 所需决策 |
| ---- | ---- | -------- |
| 无 | 无待解决问题。 | 无需决策 |

24
openspec/schemas/fast-drive/templates/tasks.md
View File

@@ -1,19 +1,19 @@
## 1. Context Review
## 1. 上下文审查
- [ ] 1.1 Read design.md and identify scope, requirements, decisions, guardrails, and open questions
- [ ] 1.2 Review relevant artifacts and references listed in Affected Areas
- [ ] 1.1 阅读 design.md，识别范围、需求、决策、执行约束和待解决问题
- [ ] 1.2 审查“影响范围”中列出的相关 artifacts 和参考资料
## 2. Execution
## 2. 执行
- [ ] 2.1 Execute first concrete work item from design.md
- [ ] 2.2 Execute next concrete work item from design.md
- [ ] 2.1 执行 design.md 中的第一个具体工作项
- [ ] 2.2 执行 design.md 中的下一个具体工作项
## 3. Validation
## 3. 验证
- [ ] 3.1 Run required validation from Verification Plan
- [ ] 3.2 Perform quality checks required by the project or workflow
- [ ] 3.3 Perform required manual review or acceptance checks from Verification Plan
- [ ] 3.1 执行“验证计划”中要求的验证
- [ ] 3.2 执行项目或 workflow 要求的质量检查
- [ ] 3.3 执行“验证计划”中要求的人工审查或验收检查
## 4. Documentation / Communication
## 4. 文档 / 沟通
- [ ] 4.1 Update relevant documentation, runbooks, communication materials, or project references if behavior, process, interface, configuration, or usage changed
- [ ] 4.1 如果行为、流程、接口、配置或使用方式发生变化，更新相关文档、runbook、沟通材料或项目参考资料