software-lifecycle

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Software Lifecycle pack — how to work here

Software Lifecycle 包——在此项目中如何工作

This project holds the doc lifecycle for an engineering team or OSS project. The flow is proposals → decisions → specs → postmortems, with guides as the how-to bucket. This skill holds the workflow so templates and folder descriptions stay clean.

This skill is pack guidance. The platform
/open-knowledge
skill (read/write/preview/linking/grounding rules) still governs every markdown operation — this layers the lifecycle conventions on top.

本项目承载工程团队或 OSS 项目的文档生命周期。流程是 提案 → 决策 → 规格 → 复盘，并将指南作为操作指南的分类。此 skill 承载工作流，使模板和文件夹说明保持简洁。

此 skill 是 pack 级指导。平台的
/open-knowledge
skill（读取/写入/预览/链接/grounding 规则）仍约束所有 Markdown 操作——本 skill 在此基础上叠加生命周期约定。

The flow

流程

proposals/    in-flight RFC-shape design proposals
   ↓ accepted
decisions/    frozen ADRs (the record of what was decided)
   ↓ derived
specs/        implementation specs for accepted proposals
   ↓ when things break
postmortems/  blameless incident write-ups
guides/       how-to / onboarding / runbooks (referenced throughout)

proposals/    in-flight RFC-shape design proposals
   ↓ accepted
decisions/    frozen ADRs (the record of what was decided)
   ↓ derived
specs/        implementation specs for accepted proposals
   ↓ when things break
postmortems/  blameless incident write-ups
guides/       how-to / onboarding / runbooks (referenced throughout)

Per-folder rules + agent behaviors

各文件夹规则与 Agent 行为

proposals/
— One file per proposal (

0001-feature-name.md

). Status flows

draft → fcp → accepted/rejected

. An accepted proposal graduates to a record in

decisions/

. Shape: Motivation / Design / Drawbacks / Alternatives / Unresolved questions. Agent: when a proposal sits at
status: draft
more than 14 days, surface it for the author to advance, park, or close.

decisions/
— Architecture Decision Records (MADR / Nygard shape). Frozen once accepted. One file per decision (

NNNN-title.md

); status

proposed/accepted/deprecated/superseded

. A new decision that supersedes an older one links back via

Supersedes:

. Agent: on a new decision, scan existing records touching the same subsystem and surface
Supersedes:
candidates before commit.

specs/
— Implementation specs derived from accepted proposals. Prefer the

github/spec-kit

shape: one folder per spec (

specs/NNN-name/

) with

spec.md

plan.md

tasks.md

(the pack ships all three templates). References the parent proposal. Agent: when a spec moves to
status: shipped
, suggest a postmortem template if the owner reports an incident in the spec's subsystem.

postmortems/
— Blameless incident write-ups, one file per incident (

YYYY-MM-DD-name.md

): Summary / Timeline / Root cause / What went well / Action items (Google SRE shape). Agent: surface a
Related:
block linking prior postmortems that share subsystems.

guides/
— How-to guides, onboarding docs, and service-bound runbooks (Diátaxis how-to). Ships

guide

onboarding-guide

, and

runbook

templates. Carries

last_verified

so stale guides surface in periodic reviews. Agent: when a postmortem is published, scan its action items for guide-shaped follow-ups and stub a guide pre-filled with the symptom and timeline excerpt.

proposals/
——每个提案一个文件（

0001-feature-name.md

）。状态流为

draft → fcp → accepted/rejected

。提案被接受后，将转入

decisions/

中的一条记录。结构：动机 / 设计 / 缺点 / 替代方案 / 未决问题。Agent：当提案处于
status: draft
超过 14 天时，将其提示给作者，以便推进、搁置或关闭。

decisions/
——Architecture Decision Records（ADR；采用 MADR / Nygard 结构）。接受后即冻结。每个决策一个文件（

NNNN-title.md

）；状态为

proposed/accepted/deprecated/superseded

。新决策取代旧决策时，通过

Supersedes:

回链旧决策。Agent：创建新决策时，扫描涉及相同子系统的现有记录，并在 commit 前提示可作为
Supersedes:
候选项的记录。

specs/
——从已接受提案派生的实现规格。优先采用

github/spec-kit

结构：每份规格一个文件夹（

specs/NNN-name/

），其中包含

spec.md

plan.md

tasks.md

（此包提供全部三个模板）。规格会引用父级提案。Agent：当规格进入
status: shipped
时，如果负责人报告该规格所属子系统发生事故，建议使用 postmortem 模板。

postmortems/
——无责事故复盘文档，每个事故一个文件（

YYYY-MM-DD-name.md

）：摘要 / 时间线 / 根因 / 做得好的地方 / 行动项（采用 Google SRE 结构）。Agent：提示添加
Related:
区块，以链接涉及相同子系统的历史 postmortem。

guides/
——操作指南、onboarding 文档和服务级 runbook（Diátaxis how-to）。提供

guide

、

onboarding-guide

和

runbook

模板。包含

last_verified

字段，以便在定期审查中标出过期指南。Agent：当 postmortem 发布时，扫描其行动项，找出适合形成指南的后续事项，并创建一个预填了症状和时间线摘录的指南存根。

The five workflows

五个工作流

Authoring in this project is procedural, not conventional. Each workflow ships as its own skill so it loads only when the work calls for it — reach for the one that matches the task rather than writing into a folder from scratch.

Workflow	Sibling skill	When
Frame a proposal	`/frame-a-proposal`	A change needs designing and arguing before anyone builds it.
Write a spec	`/write-a-spec`	An accepted proposal needs scoping into an implementable spec.
Record a decision	`/record-a-decision`	A decision was actually made and needs its context and consequences preserved.
Write a postmortem	`/write-a-postmortem`	An incident happened and the team needs a blameless write-up.
Review a design	`/review-a-design`	An existing proposal, spec, or decision needs pressure-testing for soundness.

在此项目中编写文档要遵循流程，而不是采用惯常做法。每个工作流都作为独立 skill 提供，只会在工作需要时加载——应选择与任务匹配的 skill，而不是直接从头向文件夹中编写内容。

工作流	同级 skill	使用时机
拟定提案	`/frame-a-proposal`	一项变更需要先完成设计和论证，然后才能开始实现。
编写规格	`/write-a-spec`	已接受的提案需要界定范围，形成可实现的规格。
记录决策	`/record-a-decision`	已经实际做出某项决策，需要保留其背景和影响。
编写复盘	`/write-a-postmortem`	发生事故后，团队需要编写无责复盘文档。
评审设计	`/review-a-design`	需要严格检验现有提案、规格或决策的合理性。

Templates

模板

Create docs with

write({ document: { path, template: "<name>" } })

. Templates carry only structure (headings + frontmatter scaffold); what each section is for is described above, not repeated in the document body.

使用

write({ document: { path, template: "<name>" } })

创建文档。模板只承载结构（标题 + frontmatter 脚手架）；每个部分的用途已在上文说明，不会在文档正文中重复。