engineering-tripack-generator

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Engineering Tripack Generator

工程 Tripack 生成器

Generates or revises three standard technical documents for planning feature work in any software project. Output is designed for direct use by engineers and can be reviewed by a tech lead or PM.
The skill is stack-agnostic: discover the language, framework, architecture, and tooling from applicable project instructions and the codebase (see Project Context Discovery). Apply the scoped Go backend defaults below where relevant; the output templates adapt to the discovered project.
The tripack records binding contracts, current design choices, and remaining work. Tasks reference technical-design sections for verification. Internal structure can evolve within the authority described below; synchronize material findings so later tasks use the current assessed design.
为任何软件项目中的功能工作规划生成或修订三份标准技术文档。输出可直接供工程师使用,也可由技术负责人或 PM 评审。
该 skill 与技术栈无关:从适用的项目说明(包括 AGENTS.md 和 CLAUDE.md)以及代码库中识别语言、框架、架构和工具链(参见“项目上下文发现”)。在相关情况下应用下文限定范围的 Go 后端默认值;输出模板会根据识别到的项目进行调整。
tripack 记录约束性契约、当前设计选择和剩余工作。任务引用 technical-design.md 的相关章节进行验证。内部结构可以在下述权限范围内演进;应同步重要发现,使后续任务使用当前经评估的设计。

Project Context Discovery

项目上下文发现

Before generating anything, discover the actual project context. Never fill architecture, reuse, or schema details from assumption. This step is mandatory in every mode.
  1. Read available, applicable project instructions, including
    AGENTS.md
    and
    CLAUDE.md
    at the root and instructions scoped to affected directories. Check their scope and precedence; neither filename automatically replaces the other. Read backend/architecture standards supplied by the user or referenced by those instructions, including their directory rules. Record the applicable path and section; a standard need not be named AGENTS.md or CLAUDE.md to apply. For Go backend work, read the bundled Backend Service Standard as the default baseline. Explicit user and project instructions take precedence over this baseline. Apply its layer layout to Clean Architecture services; for other architectures or languages, retain the project's applicable standards. Extract:
    • Tech stack (language, framework, database, API style — REST/gRPC/GraphQL/etc.)
    • Directory structure and where each kind of code lives
    • Code behavior conventions, patterns, and project-specific rules
    • Tooling (migration and seeding tools, codegen, test commands, lint)
  2. Verify and complete the picture from the codebase: package/module structure, one or two similar existing features/flows as pattern references, interface definition files (proto/OpenAPI/GraphQL schema/route definitions), and the migrations directory, seeders, and reference-data sources if they exist. For reference flows, explain which parts fit the new need and which limitations matter. Separate mandatory conventions from incidental existing structure. Existing code establishes current behavior, not design correctness; justify retention through the Evidence before precedent criteria in
    references/design-assessment.md
    . Assessing suitability does not authorize unrelated legacy cleanup.
  3. Derive the project's layer/component names from what you find (e.g. handler/service/repository, controller/model/view, or whatever the project uses). Use the project's own vocabulary in all output documents. For directory and package choices, follow explicit applicable standards first; where silent, follow consistent repository conventions that fit the assessed requirements. If neither settles the choice, select the simplest structure that meets the requirements. Record material choices, their source or convention, and reasons in the technical design; distinguish required placement from a design choice. Resolve conflicts between binding instructions under Design Authority and Handoff.
  4. Ask only about material information still missing or unresolved conflicts after discovery. A missing instruction file alone is not a blocker. Discovery is done when the affected components, applicable constraints, usable references, and remaining material uncertainties are identified and grounded in available sources.
在生成任何内容之前,先发现真实的项目上下文。绝不要根据假设填充架构、复用或 schema 细节。 此步骤在所有模式下均为强制要求。
  1. 阅读可用且适用的项目说明,包括根目录及受影响目录范围内的
    AGENTS.md
    和
    CLAUDE.md
    。检查其作用域和优先级;任一文件名都不会自动替代另一文件。阅读用户提供或这些说明引用的后端/架构标准,包括其目录规则。记录适用路径和章节;标准不必名为 AGENTS.md 或 CLAUDE.md 才能适用。对于 Go 后端工作,默认基线是随附的 后端服务标准。明确的用户和项目说明优先于此基线。对于采用 Clean Architecture 的服务,应用其分层布局;对于其他架构或语言,保留项目适用的标准。提取:
    • 技术栈(语言、框架、数据库、API 风格——REST/gRPC/GraphQL 等)
    • 目录结构以及各类代码的存放位置
    • 代码行为约定、模式和项目专属规则
    • 工具链(迁移和 seed 工具、代码生成、测试命令、lint)
  2. 通过代码库核实并补全情况:package/module 结构、一到两个类似现有功能/流程作为模式参考、接口定义文件(proto/OpenAPI/GraphQL schema/route 定义),以及迁移目录、seeder 和参考数据源(如存在)。对于参考流程,说明哪些部分适合新需求,以及哪些限制会影响结果。区分强制性约定与偶然形成的现有结构。现有代码只能确立当前行为,不能证明设计正确;应依据 设计评估中“证据优先于先例”的标准,说明保留现有做法的理由。评估其适用性并不授权进行无关的遗留代码清理。
  3. 从发现结果推导项目的 layer/component 名称(例如 handler/service/repository、controller/model/view,或项目实际使用的任何名称)。所有输出文档均使用项目自身的词汇。对于目录和 package 选择,首先遵循明确适用的标准;标准未作规定时,遵循符合经评估需求且与代码库一致的约定。如果两者都无法确定选择,则采用满足要求的最简单结构。在 technical design 中记录重大选择、其来源或约定,以及相应理由;区分必需的位置要求与设计选择。按照“设计权威与交接”解决约束性说明之间的冲突。
  4. 仅在发现后仍缺失或未解决冲突的重大信息时提问。缺少说明文件本身并不构成阻塞。当受影响组件、适用约束、可用参考和剩余重大不确定性均已明确,并可追溯到现有来源时,即完成发现。

Go SQL Persistence Default

Go SQL 持久化默认值

For Go backend work using SQL, use GORM as the default for CRUD and simple queries. Explicit user and project instructions take precedence. For existing features, assess the current adapter and compatibility; this default alone does not justify converting working persistence or adding a database to the feature's scope.
  • Choose raw SQL when it improves clarity, supports complex query requirements (such as reporting, subqueries, unions, or calculations), or addresses a measured performance need. Choose by query requirements and evidence, without a raw SQL percentage target or a fixed table-count limit. Raw SQL may use GORM's
    Raw
    /
    Exec
    within the same transaction where appropriate.
  • Keep persistence models and GORM dependencies in the infrastructure adapter, separate from domain models and API DTOs. Keep business rules in their assessed owners rather than moving them into ORM hooks.
  • Plan explicit SQL migrations with
    golang-migrate
    as the default; follow any explicitly required project migration tooling. Keep schema changes reviewable through migration files rather than runtime
    AutoMigrate
    .
  • In
    technical-design.md
    , record the adapter choice, material raw SQL exceptions and reasons, model mapping, and transaction boundaries. Address relevant GORM semantics: zero-value updates (
    false
    ,
    0
    , empty strings), association query behavior and N+1 risk, and soft deletion when used. Verify behavior against the project's selected version and plan database integration checks where mocks cannot establish correctness or performance.
  • Carry those decisions into
    tactical-strategy.md
    reuse/inventory and testing, then into dependent
    task-plan.md
    tasks and their definitions of done.
对于使用 SQL 的 Go 后端工作,默认使用 GORM 处理 CRUD 和简单查询。明确的用户和项目说明优先于此默认值。对于现有功能,应评估当前 adapter 和兼容性;仅凭该默认值,不足以将可正常工作的持久化实现转换掉,也不足以将数据库引入功能范围。
  • 当原始 SQL 能提升清晰度、支持复杂查询需求(如报表、子查询、union 或计算),或满足经测量的性能需求时,选择原始 SQL。应根据查询需求和证据决策,不设原始 SQL 百分比目标或固定表数量上限。适当时,原始 SQL 可在同一事务中使用 GORM 的
    Raw
    /
    Exec
    。
  • 将持久化模型和 GORM 依赖保留在 infrastructure adapter 中,与 domain 模型和 API DTO 分离。将业务规则保留在其经评估的归属方,而不是移入 ORM hook。
  • 默认使用
    golang-migrate
    规划显式 SQL migration;如项目明确要求其他 migration 工具,则从其规定。应通过 migration 文件让 schema 变更可审查,而不是在运行时使用
    AutoMigrate
    。
  • 在
    technical-design.md
    中,记录 adapter 选择、重大的原始 SQL 例外及原因、模型映射和事务边界。处理相关的 GORM 语义:零值更新(
    false
    、
    0
    、空字符串)、关联查询行为与 N+1 风险,以及使用时的软删除。根据项目选定的版本验证行为,并在 mock 无法确认正确性或性能时规划数据库集成检查。
  • 将这些决策同步到
    tactical-strategy.md
    的复用/清单和测试中,再同步到依赖它们的
    task-plan.md
    任务及完成定义。

Master Data, Migrations, and Seed Planning

主数据、迁移与 Seed 规划

In every mode, when requirements involve persisted master/reference data, schema changes, initial data, or a user request for a seeder, read Master Data, Migrations, and Seed Planning before drafting the affected design and tasks. It covers table decisions, migration artifacts, concrete seed-data recommendations, and their implementation handoff.
在每种模式下,只要需求涉及持久化的主数据/参考数据、schema 变更、初始数据,或用户请求提供 seeder,在起草受影响的设计和任务前,先阅读 主数据、迁移与 Seed 规划。其中涵盖表决策、migration 产物、具体 seed 数据建议,以及相应的实施交接。

Input

输入

Any of the following, in any combination:
  • PRD or FSD from the product team
  • An analysis document produced earlier in the conversation or provided as a file
  • A direct feature/change description from the user
  • For Mode C: the existing tripack files (required) plus the requirement change or design/implementation finding
Discover constraints (e.g. additive only, no DB change, no domain entity change) from the input and applicable instructions. Clarify material gaps or conflicts before finalizing affected work; keep independent work moving with uncertainties visible.
以下任意输入均可,可任意组合:
  • 产品团队提供的 PRD 或 FSD
  • 对话早期生成的分析文档,或用户以文件形式提供的分析文档
  • 用户直接提供的功能/变更描述
  • 对于 Mode C:现有 tripack 文件(必需),以及需求变更或设计/实现发现
从输入及适用说明中发现约束(例如仅允许新增、不改 DB、不调整 domain entity)。在最终确定受影响工作前,澄清重大缺口或冲突;让独立工作继续推进,同时明确呈现不确定性。

Modes

模式

Detect the mode from the input and the user's intent. If ambiguous, ask.
根据输入和用户意图检测模式。如有歧义,则询问。

Mode A — New Feature

Mode A — 新功能

No related implementation exists yet. Generate a fresh tripack.
尚不存在相关实现。生成一份全新的 tripack。

Mode B — Adjustment to an Existing Feature

Mode B — 调整现有功能

The feature exists in the codebase, but no tripack (or none is provided). Before generating, perform an impact analysis against the codebase:
  • Identify affected components per layer (what is Modified vs Reused as-is)
  • Identify affected entities/schema and whether migration is needed
  • Identify backward-compatibility risks (API contract, consumers, data)
  • Build the reuse map from actual code, not assumption
Then generate a fresh tripack that incorporates the impact analysis.
该功能已存在于代码库中,但没有 tripack,或未提供 tripack。生成前,针对代码库执行 影响分析:
  • 按各层识别受影响组件(哪些需要 Modified,哪些可 Reused as-is)
  • 识别受影响的实体/schema,以及是否需要 migration
  • 识别向后兼容风险(API 契约、使用方、数据)
  • 基于实际代码构建复用映射,而不是依赖假设
然后生成一份纳入影响分析的新 tripack。

Mode C — Revision of an Existing Tripack

Mode C — 修订现有 Tripack

A tripack exists and requirements changed, or design/implementation findings justify revision while requirements remain unchanged. Implementation may be partially done. Update, do not regenerate from scratch. Steps:
  1. Baseline — compare the existing tripack against the current code state. Classify: implemented-and-conforming / implemented-but-deviating / not-yet-implemented / code-not-covered-by-design. Keep this coverage/progress classification separate from assessment of each difference: contract violation, valid structural refinement, or unresolved decision. Use code and available verification evidence; clarify material progress uncertainty rather than inferring completion from code presence alone.
  2. Impact analysis — map the change or finding onto the tripack: which design sections change, which entities/schema are affected (migration from the current actual schema, not the originally planned one), which completed work becomes invalid, and whether it contradicts earlier binding decisions. Apply Design Authority below: resolve conflicts with binding contracts/constraints through the relevant decision owner; ordinary authorized internal refinements need no new approval.
  3. Draft and assess technical-design.md — use the assessment step in How It Works. Before planning reconciliation, decide whether code, documents, or both need to change and explain why. The resulting doc must be fully self-consistent: a new reader should understand the current design without knowing its history. Record the change in the Revision History section (what changed, why).
  4. Update tactical-strategy.md — adjust reuse map, net-new inventory, testing and rollout/rollback as needed.
  5. Update task-plan.md for remaining work —
    • Preserve completed tasks and their
      [x]
      status if still valid
    • Mark invalidated tasks as
      ~~obsolete~~
      with a one-line reason (do not delete)
    • Preserve task IDs; allocate new IDs without renumbering existing tasks
    • Add code/schema reconciliation only when implementation actually needs to change; a documents-only refinement does not require a code-repair task
    • Place reconciliation before tasks that depend on its result; unrelated work can proceed
    • Mark tasks affected by unresolved decisions as blocked, with the decision and readiness condition; a deferred design is not executable for its dependents
    • Preserve Revision History and decision history, including superseded entries
已存在 tripack,且需求已变化,或设计/实现发现足以证明需要修订,而需求保持不变。实现可能只完成了一部分。进行更新,不要从头重新生成。 步骤:
  1. 基线——将现有 tripack 与当前代码状态进行比较。分类为:已实现且符合规范 / 已实现但存在偏差 / 尚未实现 / 代码未被设计覆盖。将这一覆盖/进度分类与每项差异的评估分开:契约违规、有效的结构细化或未解决的决策。使用代码和可用验证证据;应澄清重大进度不确定性,而不是仅凭代码存在就推断已完成。
  2. 影响分析——将变更或发现映射到 tripack:哪些设计章节发生变化,哪些实体/schema 受到影响(migration 必须基于当前实际 schema,而非最初计划的 schema),哪些已完成工作失效,以及它是否与先前的约束性决策冲突。应用下述“设计权威与交接”:通过相应的决策负责人解决与约束性契约/约束的冲突;普通的获授权内部细化无需新审批。
  3. 起草并评估 technical-design.md——使用“工作原理”中的评估步骤。规划协调工作前,先确定需要更改代码、文档还是两者,并解释原因。最终文档必须完全自洽:新读者无需了解历史即可理解当前设计。在 Revision History 部分记录变更(改了什么、为什么改)。
  4. 更新 tactical-strategy.md——根据需要调整复用映射、新增代码清单、测试以及发布/回滚方案。
  5. 为剩余工作更新 task-plan.md:
    • 保留已完成的任务及其
      [x]
      状态(若仍然有效)
    • 将失效任务标记为
      ~~obsolete~~
      ,并附一行原因(不要删除)
    • 保留任务 ID;新增 ID 时不得重新编号现有任务
    • 仅当实现确实需要更改时,才添加代码/schema 协调任务;仅更新文档的细化不需要代码修复任务
    • 将协调工作放在依赖其结果的任务之前;无关工作可继续推进
    • 将受未解决决策影响的任务标记为阻塞,并写明所需决策和就绪条件;延期的设计不可供其依赖任务执行
    • 保留 Revision History 和决策历史,包括被取代的条目

Design Authority and Handoff

设计权威与交接

Distinguish these in the technical design:
  • Binding contracts: business rules, accepted inputs/states, normalization, errors and their ordering, failure timing, side effects, lifecycle, and caller/data compatibility. Changes require a resolved decision appropriate to their impact and existing authority.
  • Internal structure: components, helpers, types, and placement may be refined within scope when the executor explains the benefit and supplies evidence that binding behavior remains preserved. A structural difference alone is not a defect.
  • Explicitly required structure: record the constraint, source, and reason. Resolve a conflict before changing it; a familiar existing pattern is not by itself an explicit requirement.
Treat aggregate boundaries, transaction changes, or effects outside scope as material when guarantees or responsibilities change. Assess that impact before calling a change internal. This authority does not expand the task's scope.
Material design changes affecting later tasks must be synchronized in the tripack before those tasks start. At task closure, align affected design, strategy, and task status with the result. Small local structural edits need no step-by-step history. This defines the generator's handoff; changing separate executor instructions is follow-up work.
在 technical design 中区分以下内容:
  • **约束性契约:**业务规则、允许的输入/状态、规范化、错误及其顺序、失败时机、副作用、生命周期,以及调用方/数据兼容性。变更需要根据影响范围和现有决策权限作出已解决的决策。
  • **内部结构:**组件、辅助函数、类型及其位置,可在范围内细化,只要执行者说明收益并提供证据,证明约束性行为保持不变。仅有结构差异并不构成缺陷。
  • **明确要求的结构:**记录该约束、来源和原因。变更前先解决冲突;仅仅熟悉某种现有模式,并不意味着它本身就是明确要求。
当保证或职责发生变化时,应将聚合边界、事务变更或范围外影响视为重大事项。评估该影响后,才能将变更归类为内部调整。此权限不会扩大任务范围。
影响后续任务的重大设计变更,必须在那些任务开始前同步到 tripack 中。任务关闭时,应根据结果对齐受影响的设计、策略和任务状态。小型局部结构编辑无需逐步记录历史。这定义了生成器的交接方式;更改独立的执行者说明属于后续工作。

Output

输出

Three files:
  1. technical-design.md
  2. tactical-strategy.md
  3. task-plan.md
  4. decision-log.md
    — optional, conditional: generate only when the input or analysis surfaces technical decisions driven by business decisions/constraints (see "When to generate decision-log.md" below). Never create it as an empty formality. Its audience is PM / product manager / tech lead — see the template for tone rules.
Save to the output directory specified by the user. If none is specified: save next to the input file if the input is a file; otherwise ask (suggest
./docs/<feature-name>/
as the default).

以下文件:
  1. technical-design.md
  2. tactical-strategy.md
  3. task-plan.md
  4. decision-log.md
    ——可选且有条件:仅当输入或分析揭示了由业务决策/约束驱动的技术决策时生成(见下文“何时生成 decision-log.md”)。绝不能将其创建为一种空洞的形式。其受众是 PM/product manager/tech lead——语气规则见模板。
保存到用户指定的输出目录。如果未指定:输入为文件时,保存到该输入文件旁边;否则先询问(建议默认使用
./docs/<feature-name>/
)。

Output Templates

输出模板

The templates below are the baseline structure. Adapt terminology and sections to the project discovered in Project Context Discovery — use the project's actual layer names, and rename/omit sections that don't apply (noted per section).
以下模板是基线结构。根据“项目上下文发现”中识别到的项目调整术语和章节——使用项目实际的 layer/component 名称,并重命名或省略不适用的章节(各节中已有说明)。

File 1: technical-design.md

文件 1:technical-design.md

undefined
undefined

Technical Design: [feature name]

Technical Design: [feature name]

1. Overview

1. Overview

[Brief description of the feature and its context]
[Brief description of the feature and its context]

Goals

Goals

  • [what this delivers]
  • [what this delivers]

Non-Goals

Non-Goals

  • [explicitly out of scope]
  • [explicitly out of scope]

2. API / Interface Contract Changes

2. API / Interface Contract Changes

[Adapt to the project's API style: gRPC/proto changes, REST endpoints & OpenAPI, GraphQL schema, event/message contracts, CLI commands, or public library API] [If none: "No contract changes required"]
[Adapt to the project's API style: gRPC/proto changes, REST endpoints & OpenAPI, GraphQL schema, event/message contracts, CLI commands, or public library API] [If none: "No contract changes required"]

3. Data Model & Schema Changes

3. Data Model & Schema Changes

[Assess schema and seed needs separately; "No schema changes required" does not omit a requested seeder or required initial data. Apply Master Data, Migrations, and Seed Planning when relevant.]
  • Affected entities and final schema (per the project's DB and migration tooling)
  • Migration artifacts: proposed file paths, forward changes, rollback/recovery path
  • Impact on existing data (backfill, defaults, data loss risk)
[Assess schema and seed needs separately; "No schema changes required" does not omit a requested seeder or required initial data. Apply Master Data, Migrations, and Seed Planning when relevant.]
  • Affected entities and final schema (per the project's DB and migration tooling)
  • Migration artifacts: proposed file paths, forward changes, rollback/recovery path
  • Impact on existing data (backfill, defaults, data loss risk)

Seed / Reference Data (when requested or required)

Seed / Reference Data (when requested or required)

Target tableStable keyProposed valuesPurpose / source / proposal statusEnvironments
[table][key fields and value][concrete record values, or unresolved fields][required reference / demo / test; source or decision needed][targets]
  • Delivery: [existing/proposed seeder or data-migration paths and mechanism]
  • Execution: [dependencies, rerun/conflict policy, rollback/cleanup behavior]
  • Open data decisions: [unknown required values, source/owner, affected work]
Target tableStable keyProposed valuesPurpose / source / proposal statusEnvironments
[table][key fields and value][concrete record values, or unresolved fields][required reference / demo / test; source or decision needed][targets]
  • Delivery: [existing/proposed seeder or data-migration paths and mechanism]
  • Execution: [dependencies, rerun/conflict policy, rollback/cleanup behavior]
  • Open data decisions: [unknown required values, source/owner, affected work]

Concepts and rules (when domain models/rules are affected)

Concepts and rules (when domain models/rules are affected)

  • Business concepts/terms, their meaning, and the context where each applies
  • Identity/lifecycle, value semantics, and consistency boundaries where relevant
Material ruleOwnerEnforcement pathsProof plan
[rule/invariant][responsible component/model][creation/restoration/transition/other callers][observable cases and verification]
[For changes without domain impact: state that domain assessment is not applicable and why. Record any material non-domain rules with their owners in component details.]
  • Business concepts/terms, their meaning, and the context where each applies
  • Identity/lifecycle, value semantics, and consistency boundaries where relevant
Material ruleOwnerEnforcement pathsProof plan
[rule/invariant][responsible component/model][creation/restoration/transition/other callers][observable cases and verification]
[For changes without domain impact: state that domain assessment is not applicable and why. Record any material non-domain rules with their owners in component details.]

4. Component Breakdown

4. Component Breakdown

[Use the project's actual layers/components as rows — discovered, not assumed]
Layer/ComponentStatusJustification
[project's layer 1]New / Modified / Reused as-is...
[project's layer 2]New / Modified / Reused as-is...
[Use the project's actual layers/components as rows — discovered, not assumed]
Layer/ComponentStatusJustification
[project's layer 1]New / Modified / Reused as-is...
[project's layer 2]New / Modified / Reused as-is...

Detail per component

Detail per component

[For each New or Modified component: explain what changes and why; include material non-domain rules, owners, enforcement paths, and proof plans not covered above]
[For each New or Modified component: explain what changes and why; include material non-domain rules, owners, enforcement paths, and proof plans not covered above]

Material structure decisions and assessment

Material structure decisions and assessment

ChoiceReason and material alternatives/tradeoffsAuthority and refinement boundaryAssessment outcome
[chosen or retained structure][concrete benefit/cost vs viable alternative][internal choice / explicit constraint with source and reason; binding guarantees][retained / revised / deferred, reason and decision needed]
[Scale detail to impact; a simple retained structure can need only a brief reason. Keep assessment in these design sections rather than a separate report/checklist.]
ChoiceReason and material alternatives/tradeoffsAuthority and refinement boundaryAssessment outcome
[chosen or retained structure][concrete benefit/cost vs viable alternative][internal choice / explicit constraint with source and reason; binding guarantees][retained / revised / deferred, reason and decision needed]
[Scale detail to impact; a simple retained structure can need only a brief reason. Keep assessment in these design sections rather than a separate report/checklist.]

5. Flow Sequence

5. Flow Sequence

[Step-by-step from entry point to result — request/response, event handling, job execution, or whatever fits the feature]
  1. [step 1]
  2. [step 2]
[Step-by-step from entry point to result — request/response, event handling, job execution, or whatever fits the feature]
  1. [step 1]
  2. [step 2]

6. Request / Response (or Input / Output)

6. Request / Response (or Input / Output)

[Diff or full spec of new input and output vs existing if changed]
[Diff or full spec of new input and output vs existing if changed]

Creation, restoration, and transition contracts (when relevant)

Creation, restoration, and transition contracts (when relevant)

PathAccepted inputs/states and normalizationErrors/order and failure timingSide effects and compatibilityProof plan
[new input / load persisted state / state transition][path-specific policy][observable behavior][caller/data/effects][cases to verify]
[Explain whether restoration trusts, validates, normalizes, or migrates stored state. Share policy only where the path contracts agree; note inapplicability briefly.]
PathAccepted inputs/states and normalizationErrors/order and failure timingSide effects and compatibilityProof plan
[new input / load persisted state / state transition][path-specific policy][observable behavior][caller/data/effects][cases to verify]
[Explain whether restoration trusts, validates, normalizes, or migrates stored state. Share policy only where the path contracts agree; note inapplicability briefly.]

7. Error Handling

7. Error Handling

[New errors added, their propagation path]
[New errors added, their propagation path]

8. Constraints Checklist

8. Constraints Checklist

  • [constraint 1 from input]
  • [constraint 2 from input]
  • [constraint 1 from input]
  • [constraint 2 from input]

9. Risks & Open Questions

9. Risks & Open Questions

[Implementation risks, unresolved questions, and deferred assessment decisions. For each blocker: affected components/task IDs, decision owner or source needed, and condition for readiness. Independent tasks may remain executable.]
[Implementation risks, unresolved questions, and deferred assessment decisions. For each blocker: affected components/task IDs, decision owner or source needed, and condition for readiness. Independent tasks may remain executable.]

10. Revision History

10. Revision History

VersionDateChangeReason
v1[date]Initial design—
undefined
VersionDateChangeReason
v1[date]Initial design—
undefined

File 2: tactical-strategy.md

文件 2:tactical-strategy.md

undefined
undefined

Tactical Strategy: [feature name]

Tactical Strategy: [feature name]

1. Implementation Strategy

1. Implementation Strategy

[Additive-only / breaking change / mixed — and the chosen approach]
[Additive-only / breaking change / mixed — and the chosen approach]

2. Code Reuse Map

2. Code Reuse Map

ComponentLocationUsed forFit and limitations
[function/class/module name][package/file][purpose][what fits; relevant gaps]
ComponentLocationUsed forFit and limitations
[function/class/module name][package/file][purpose][what fits; relevant gaps]

3. Net-New Code Inventory

3. Net-New Code Inventory

ItemLayer/ComponentPackage/PathTypeOwnership / Notes
[name][component][planned location][aggregate root/value object/handler/etc.][owner or relationship; purpose]
[Classify each item by its responsibility and domain characteristics, independently of its package location. Give an aggregate root and its value objects separate rows, even when they share a package. Record ownership as a relationship. Describe a predicate as behavior of its owner when appropriate; a separate row does not require a separate type, file, or package. Include planned migration and seed artifacts from design §3; put reused artifacts in the reuse map.]
ItemLayer/ComponentPackage/PathTypeOwnership / Notes
[name][component][planned location][aggregate root/value object/handler/etc.][owner or relationship; purpose]
[Classify each item by its responsibility and domain characteristics, independently of its package location. Give an aggregate root and its value objects separate rows, even when they share a package. Record ownership as a relationship. Describe a predicate as behavior of its owner when appropriate; a separate row does not require a separate type, file, or package. Include planned migration and seed artifacts from design §3; put reused artifacts in the reuse map.]

4. Branching / PR Strategy

4. Branching / PR Strategy

[Recommendation: one large PR or split, safe merge order; commit per task]
[Recommendation: one large PR or split, safe merge order; commit per task]

5. Testing Strategy

5. Testing Strategy

[Use the project's verified test framework and commands from applicable instructions (including AGENTS.md / CLAUDE.md) and codebase. Derive cases from assessed rule ownership and path contracts; distinguish planned checks from existing evidence.]
[Use the project's verified test framework and commands from applicable instructions (including AGENTS.md / CLAUDE.md) and codebase. Derive cases from assessed rule ownership and path contracts; distinguish planned checks from existing evidence.]

Unit Tests

Unit Tests

  • [what to unit test, focus on new logic]
  • [what to unit test, focus on new logic]

Integration Tests

Integration Tests

  • Happy path: [scenario]
  • Error cases: [scenario per new error]
  • Happy path: [scenario]
  • Error cases: [scenario per new error]

Regression Tests

Regression Tests

  • [existing endpoints or flows that must still pass]
  • [existing endpoints or flows that must still pass]

6. Rollout & Rollback

6. Rollout & Rollback

  • Rollout: [feature flags, phased rollout, monitoring to add]
  • Rollback: [trigger conditions, how to revert code and migrations safely]
undefined
  • Rollout: [feature flags, phased rollout, monitoring to add]
  • Rollback: [trigger conditions, how to revert code and migrations safely]
undefined

File 3: task-plan.md

文件 3:task-plan.md

undefined
undefined

Task Plan: [feature name]

Task Plan: [feature name]

Legend

Legend

  • ID: T1, T2, ... (stable — never renumber on revision)
  • Complexity: S (< 2h) | M (2–4h) | L (> 4h)
  • Status: [ ] Todo | [~] In Progress | [x] Done | obsolete
  • ref: technical-design.md section this task implements
  • DoD: definition of done (verifiable)
  • Blocked: decision/prerequisite and readiness condition; not executable until resolved
  • ID: T1, T2, ... (stable — never renumber on revision)
  • Complexity: S (< 2h) | M (2–4h) | L (> 4h)
  • Status: [ ] Todo | [~] In Progress | [x] Done | obsolete
  • ref: technical-design.md section this task implements
  • DoD: definition of done (verifiable)
  • Blocked: decision/prerequisite and readiness condition; not executable until resolved

Tasks

Tasks

Reconciliation (Mode C only — when code/schema changes are needed)

Reconciliation (Mode C only — when code/schema changes are needed)

[Must precede dependent tasks. Omit for a documents-only revision.]
  • T1. [align existing code/schema with revised design] — [Component] — [S/M/L] — depends: none — ref: design §X — DoD: [criteria]
[Must precede dependent tasks. Omit for a documents-only revision.]
  • T1. [align existing code/schema with revised design] — [Component] — [S/M/L] — depends: none — ref: design §X — DoD: [criteria]

Sequential (must be done in order)

Sequential (must be done in order)

[Include explicit migration and seed tasks when applicable, with artifact paths, dependencies, and verifiable DoD from design §3.]
  • T2. [Task title] — [Component] — [S/M/L] — depends: T1 — ref: design §X — DoD: [e.g. tests pass, lint clean, endpoint callable]
[Include explicit migration and seed tasks when applicable, with artifact paths, dependencies, and verifiable DoD from design §3.]
  • T2. [Task title] — [Component] — [S/M/L] — depends: T1 — ref: design §X — DoD: [e.g. tests pass, lint clean, endpoint callable]

Parallel (can be done simultaneously)

Parallel (can be done simultaneously)

  • T5. [Task title] — [Component] — [S/M/L] — depends: T1 — ref: design §Y — DoD: [criteria]
  • T5. [Task title] — [Component] — [S/M/L] — depends: T1 — ref: design §Y — DoD: [criteria]

Blocked / Deferred (when applicable)

Blocked / Deferred (when applicable)

  • T6. [Affected work] — [Component] — [S/M/L] — depends: [decision/task] — ref: design §X — blocked by: [decision and owner/source] — ready when: [resolved choice and synchronized design] — DoD: [criteria]
  • T6. [Affected work] — [Component] — [S/M/L] — depends: [decision/task] — ref: design §X — blocked by: [decision and owner/source] — ready when: [resolved choice and synchronized design] — DoD: [criteria]

Dependency Graph

Dependency Graph

T1 → T2 T1 → T5 (parallel with T2)
undefined
T1 → T2 T1 → T5 (parallel with T2)
undefined

File 4 (optional): decision-log.md

文件 4(可选):decision-log.md

When to generate decision-log.md: only when the input (PRD/FSD/analysis/user statements) or the impact analysis reveals technical decisions that are driven by business decisions or constraints — e.g. a product rule shaping where logic lives, a deadline forcing a simplification, a compliance/regulatory requirement dictating architecture, a pricing/tier decision shaping access control. Pure technical trade-offs (library choice, internal patterns) do NOT belong here — they stay in technical-design.md Justifications. If no business-driven decision exists, do not create the file, and say so in the final summary.
Audience & tone: written for PM / product manager / tech lead. Business-first ordering, plain language, no unexplained jargon. A PM must be able to read every entry without an engineer translating.
undefined
何时生成 decision-log.md: 仅当输入(PRD/FSD/分析/用户陈述)或影响分析揭示了由业务决策或约束驱动的技术决策时才生成——例如,产品规则影响逻辑所在位置、上线期限迫使方案简化、合规/监管要求决定架构,或定价/套餐决策决定访问控制。纯技术权衡(库选择、内部模式)不属于这里——应保留在 technical-design.md 的理由说明中。如果不存在业务驱动的决策,则不要创建该文件,并在最终总结中说明原因。
**受众与语气:**面向 PM/product manager/tech lead 编写。按业务优先的顺序组织,使用通俗语言,不使用未经解释的术语。即使没有工程师协助翻译,PM 也必须能够读懂每个条目。
undefined

Decision Log: [feature name]

Decision Log: [feature name]

Technical decisions in this feature that exist because of business decisions or constraints. Each entry records why, what it means for the product, and when it should be revisited.
Technical decisions in this feature that exist because of business decisions or constraints. Each entry records why, what it means for the product, and when it should be revisited.

D1: [short decision title, plain language]

D1: [short decision title, plain language]

  • Business driver: [the business decision/constraint that triggered this, and who decided it — e.g. "Feature is premium-only (decided by PM, PRD §2)"]
  • Technical decision: [what was chosen, explained in plain language]
  • What this means for the product: [observable consequence for users/business — e.g. "free users get a clear upgrade prompt instead of an error"]
  • Alternatives considered: [briefly, and why rejected — fair, no strawman]
  • Trade-offs accepted: [honest, including the negative ones]
  • Revisit when: [the business condition that should trigger re-evaluating this — e.g. "if the feature opens to all tiers" / "after launch deadline passes"]
  • Status: active | superseded by D[x] (on [date], reason)

Decision IDs (D1, D2, ...) are stable and referenceable from technical-design.md
(e.g. "caching skipped — see decision-log D2") and from Component Breakdown
Justifications.

---
  • Business driver: [the business decision/constraint that triggered this, and who decided it — e.g. "Feature is premium-only (decided by PM, PRD §2)"]
  • Technical decision: [what was chosen, explained in plain language]
  • What this means for the product: [observable consequence for users/business — e.g. "free users get a clear upgrade prompt instead of an error"]
  • Alternatives considered: [briefly, and why rejected — fair, no strawman]
  • Trade-offs accepted: [honest, including the negative ones]
  • Revisit when: [the business condition that should trigger re-evaluating this — e.g. "if the feature opens to all tiers" / "after launch deadline passes"]
  • Status: active | superseded by D[x] (on [date], reason)

Decision ID(D1、D2 等)保持稳定,并可供 technical-design.md(例如“caching skipped — see decision-log D2”)及 Component Breakdown Justifications 引用。

---

How It Works

工作原理

  1. Discover project context from applicable instructions (including AGENTS.md and CLAUDE.md) and verified code — see Project Context Discovery. Identify the mode (A/B/C) and clarify material gaps/conflicts in constraints.
  2. Analyze/baseline — Mode A: map requirements and affected boundaries. Mode B: impact analysis against the codebase. Mode C: baseline + impact analysis against the existing tripack and code, with separate coverage and difference assessments. Finish with affected behavior, reuse, and compatibility risks known or explicitly identified as unresolved.
  3. Draft technical-design.md — what is new/reused, rule ownership and enforcement, path contracts, structure choices, and explicit constraints. Apply Master Data, Migrations, and Seed Planning to schema/data work and user-requested seeders. Record business-driven decisions in decision-log.md when applicable; keep technical reasons in the design.
  4. Assess and refine the design — read Design Assessment in every mode before deriving strategy/tasks. Apply domain criteria when the change affects models/rules; briefly explain inapplicability otherwise. Record retained/revised/deferred outcomes within the technical design. This step is done when every material rule has an owner, enforcement path, and proof plan, every material structure choice has a reason and refinement boundary, and blockers identify affected work and readiness conditions. Deferred choices remain blocked for dependent tasks; continue planning independently settled work.
  5. Generate/update tactical-strategy.md from the assessed design — reuse, net-new work, safe order, and verification for material rules and contracts. Cover happy paths, new errors, relevant creation/restoration/transitions, and regression.
  6. Generate/update task-plan.md from that strategy — granular tasks, each independently verifiable and completable in one implementation session. Every task has: stable ID, title, component, complexity, dependency, design-section ref, and DoD. Mark decision-blocked tasks explicitly. In Mode C, decide reconciliation direction before adding work.
  7. Check consistency — design outcomes, reuse/inventory, test strategy, task dependencies, and DoD must agree. Check each material rule/contract has planned verification and no dependent task is marked ready with a blocking decision open. Check that each planned schema change has migration artifacts/tasks, and each requested or required seeder has a dataset recommendation or an explicit data decision blocking affected work; trace both through inventory, rollout, and DoD. In Mode C, preserve valid task IDs/status and revision/decision history. When an active business-driven decision is contradicted, surface it to the user; after resolution, mark the old entry
    superseded by D[x]
    (never delete it) and add the new entry. Synchronize affected documents before handing off dependent tasks.
  8. Save the files and summarize: mode used, key decisions, whether a decision-log was produced (and why not, if skipped), assessment outcomes, and open decisions with their blocked work.
  1. 发现项目上下文——从适用说明(包括 AGENTS.md 和 CLAUDE.md)和已验证代码中获取信息,参见“项目上下文发现”。识别模式(A/B/C),并澄清约束中的重大缺口/冲突。
  2. 分析/建立基线——Mode A:映射需求与受影响边界。Mode B:针对代码库执行影响分析。Mode C:针对现有 tripack 和代码执行基线 + 影响分析,并分别进行覆盖评估和差异评估。最终明确受影响行为、复用情况和兼容性风险,或将其明确标记为未解决。
  3. 起草 technical-design.md——说明新增/复用内容、规则归属与执行方式、路径契约、结构选择和明确约束。对 schema/数据工作应用“主数据、迁移与 Seed 规划”。适用时,在 decision-log.md 中记录业务驱动决策;将技术原因保留在设计中。
  4. 评估并细化设计——所有模式下,在推导策略/任务前都要阅读 设计评估。当变更影响模型/规则时,应用领域标准;否则简要说明为何不适用。在 technical design 中记录保留、修订或延期的结果。只有当每项重大规则都有归属方、执行路径和验证方案,每项重大结构选择都有理由和细化边界,且阻塞项均标明受影响工作和就绪条件时,才算完成此步骤。延期选择的相关任务仍保持阻塞;继续规划已独立确定的工作。
  5. 根据经评估的设计生成/更新 tactical-strategy.md——涵盖复用、新增工作、安全执行顺序,以及对重大规则和契约的验证。覆盖正常路径、新错误、相关创建/恢复/转换场景和回归测试。
  6. 根据策略生成/更新 task-plan.md——拆分为颗粒化任务,每项都可独立验证,并可在一次实施会话中完成。每项任务都包含:稳定 ID、标题、组件、复杂度、依赖关系、设计章节引用和 DoD。明确标记受决策阻塞的任务。在 Mode C 中,添加工作前先确定协调方向。
  7. 检查一致性——设计结果、复用/清单、测试策略、任务依赖关系和 DoD 必须一致。检查每项重大规则/契约都有计划中的验证,且没有依赖任务在阻塞决策仍未解决时标记为就绪。检查每项计划中的 schema 变更都有 migration 产物/任务,每个已请求或必需的 seeder 都有数据集建议,或有明确的数据决策阻塞受影响工作;将两者贯穿清单、发布和 DoD 进行追踪。在 Mode C 中,保留有效的任务 ID/状态以及修订/决策历史。当活动中的业务驱动决策与新内容矛盾时,向用户提出;解决后,将旧条目标记为
    superseded by D[x]
    (绝不删除),并添加新条目。在交接依赖任务前,同步受影响文档。
  8. 保存文件并总结:说明使用的模式、关键决策、是否生成了 decision-log(若跳过则说明原因)、评估结果,以及未解决决策及其阻塞的工作。

Rules

规则

  • All output documents must be written in English, regardless of conversation language
  • Use the project's own layer/component names and conventions as discovered from applicable project instructions (including AGENTS.md and CLAUDE.md) and verified code; assess reference-flow suitability within scope instead of copying structure automatically
  • Do not write implementation code — design and planning only
  • Never fill the reuse map, component status, or schema details from assumption — verify against the codebase first
  • Surface blocking questions with their affected work; keep dependent tasks blocked until resolved and continue independently settled planning
  • In Mode C, never silently drop prior decisions: contradictions between old and new requirements or findings must be assessed under Design Authority, and history is preserved via Revision History, obsolete task markers, and
    superseded
    decision-log entries
  • Apply the assessment completion gate before strategy/tasks. Internal refinements follow Design Authority and Handoff; documents-only updates require no code repair
  • decision-log.md is conditional: create it only when business-driven technical decisions exist; keep its language accessible to PM/PO (plain language, no unexplained jargon), unlike the other three files which target engineers
  • Task IDs are stable across revisions — add new IDs, never renumber
  • Complexity estimates (S/M/L) are rough — engineers must still validate
  • 所有输出文档必须使用英文撰写,无论对话语言为何
  • 使用从适用项目说明(包括 AGENTS.md 和 CLAUDE.md)和已验证代码中发现的 layer/component 名称与约定;在范围内评估参考流程的适用性,而不是自动复制其结构
  • 不要编写实现代码——只做设计和规划
  • 绝不要根据假设填写复用映射、组件状态或 schema 细节——先针对代码库进行验证
  • 提出阻塞性问题并说明其受影响工作;依赖项保持阻塞直到问题解决,同时继续规划已独立确定的工作
  • 在 Mode C 中,绝不悄悄丢弃先前决策:旧/新需求或发现之间的矛盾必须依据“设计权威与交接”进行评估,并通过 Revision History、
    ~~obsolete~~
    任务标记和
    superseded
    decision-log 条目保留历史
  • 在推导策略/任务前应用评估完成门禁。内部细化遵循“设计权威与交接”;仅更新文档无需代码修复
  • decision-log.md 是条件性的:仅在存在业务驱动的技术决策时创建;其语言应便于 PM/PO 阅读(表达直白,不使用未经解释的术语),而其他三份文档面向工程师
  • 任务 ID 在修订间保持稳定——新增 ID,绝不重新编号
  • 复杂度估算(S/M/L)仅供粗略参考——工程师仍须验证