by-tech-plan

by-tech-plan

Use this skill to assist R&D colleagues in producing technical solution documents that are reviewable, implementable, and releasable. The focus is not filling out a template, but first identifying requirement complexity, exposing hidden assumptions, clarifying key trade-offs, and leaving behind a solution that R&D, testing, release, and operations teams can jointly execute.

The final document must first follow Solution Type Identification to select the output structure. Risk assessment must be completed, but only the risk dimensions that are hit need to be expanded in the main text; dimensions that are not hit may be omitted, or explained in one sentence as "not involved, because...". L2/L3 use the full template, L0/L1 use the lightweight template.

Pre-start Actions

Before starting interrogation or drafting, first clarify what the user truly wants to accomplish this time.

• First restate the requirement goal you understand in one sentence, for example: "I understand that this time we need to produce a reviewable technical solution for {requirement/project}, focusing on solving {core problem}."
• If the user has not provided materials, proactively request supplementary usable inputs: PRD/requirement document, Feishu document, interface document, code repository address, target branch, related modules, historical solutions, or online issue links.
• If the user has already provided some materials, first confirm what role each of these materials plays: PRD, technical background, existing implementation, interface constraints, testing basis, or release constraints.
• If the code repository address or document address is temporarily unavailable, do not block either. Explain that you will proceed based on the current context first, and record the missing materials in Issue Record。
• Clarify the deliverable form: whether only a Markdown draft is needed, a Feishu document needs to be updated, main text that can be copied into a template needs to be generated, or the user needs to be accompanied through multiple rounds of refinement.

Pre-solution Calibration

Before entering interrogation or drafting, do a brief calibration first to avoid silently choosing the wrong direction.

• Restate the requirement goal you understand: what problem exactly is to be solved this time.
• Clarify the success criteria for this phase: what result must appear for this phase's solution to be acceptable.
• Distinguish the current information status: which are confirmed facts, which are recommended assumptions, and which are issues to be confirmed.
• If multiple interpretations exist, list the different interpretations and their impacts; do not silently choose on behalf of the user.
• If a P0 blocking decision cannot be confirmed from the materials, ask first; if it is only P1/P2 information, give a recommended assumption and continue advancing.

Solution Type Identification

Before drafting, first give the recommended solution type and explain the basis for the judgment. By default, start from the lightweight type, and upgrade only after risk trigger conditions are hit; do not default to the full template from the start.

Type	Applicable Scenarios	Output Focus
L0 Delivery Execution Sheet	Clear requirements, single-point changes, no architectural trade-offs, no database table/interface contract/cross-system impact	Change details, execution steps, acceptance method
L1 Lightweight Technical Solution	Single system or single module, with a small number of process, interface, configuration, or page adjustments, but with locally controllable risk	Solution details, core process, design of involved items, verification and launch
L2 Standard Technical Solution	Multi-module or multi-system collaboration, involving database tables, interface contracts, compatibility, canary release, data migration, or operational observation	Use the complete 9-chapter template, and elaborate on key designs and trade-offs
L3 In-depth Review Solution	Core transaction/funds/fulfillment链路, strong consistency, high concurrency, security permissions, external dependencies, or complex rollback	On the basis of L2, strengthen ADR, stress testing, monitoring, emergency plans, and manual recovery

When any of the following conditions is met, L0 cannot be used; when multiple items are met or the core链路 is affected, prioritize upgrading to L2/L3:

• Adding or modifying database tables, indexes, state machines, cache structures, message bodies, or scheduled tasks.
• Changes to external contracts such as HTTP/RPC/MQ/Event, or the need to be compatible with old clients, old data, or old configurations.
• Cross-system, cross-repository, or cross-team releases, or the existence of explicit release order dependencies.
• Involves asynchrony, retries, compensation, idempotency, concurrent consistency, distributed locks, or rate limiting and degradation.
• Involves historical data migration, backfilling, cleansing, permissions, privacy, security, auditing, or risk control.
• Rollback cost is high, or failure will affect core businesslinks, funds, orders, fulfillment, billing, or settlement.

If the user explicitly requests a lightweight output, but the materials meet the upgrade conditions, first point out the reason for the upgrade, then provide a "lightweight main text + risk appendix" or recommend using L2/L3.

L0/L1 Solution Details First

L0/L1 is not a scaled-down complete technical solution, but a solution details document oriented toward delivery. The main text should prioritize answering "specifically how to change it, in what steps to do it, how to accept it, and how to launch/roll back," and omit other modules as much as possible.

• Background, goals, and non-goals should retain only necessary information, usually 1-3 sentences is sufficient.
• Do not separately elaborate modification history, staffing arrangements, operations plans, solution pros and cons, complete architecture diagrams, capacity stress testing, or ADRs, unless the risk scan hits.
• Do not write long paragraphs of "none" or "not involved" for the sake of template completeness; when explanation is truly needed, put one sentence under the relevant details.
• The "solution details" of L0/L1 must come first, and the main length must not be placed on background, requirement breakdown, or management information.
• If the solution details are unclear, prioritize supplementing the change table, steps, inputs and outputs, state changes, configuration items, interface fields, or acceptance examples, rather than adding generalized chapters.

Work Mode

Select a mode according to the current context.

1. Interrogation Mode

When the user only has a rough idea, a PRD link, a half-finished solution, or explicitly says "help me sort it out/help me improve it/help me interrogate the solution," use Interrogation Mode.

• Do not mechanically "ask only one question at a time." First divide the questions into three categories, then decide the interaction rhythm:
  • P0 Blocking Decision: Failure to confirm will affect the solution direction, system boundaries, data ownership, main solution trade-offs, database table design, compatibility strategy, or launch and rollback. Confirm P0 questions one by one, with at most 1-3 raised in a single round.
  • P1 Important Assumption: Affects solution quality, but can proceed first based on the recommended answer. Confirm P1 questions in batches, with at most 5-8 per batch.
  • P2 Non-blocking Information: Information such as the owner, exact scheduling, metric thresholds, and exact data volume values that do not affect the draft direction for now, directly adopt the recommended assumptions and write them into Issue Log。
• For each question, first give your recommended answer, the basis for the judgment, and what would be affected if the judgment is wrong, then ask the user to confirm or correct it.
• During batch confirmation, allow the user to reply "continue with all recommendations". When the user corrects only some questions, the uncorrected items adopt the recommended answers by default, and in Issue Log mark them as "assumptions pending confirmation".
• When P0 is already clear and both P1/P2 already have recommended judgments, enter synthesis mode and first do an information playback; after the user confirms, corrects, or asks to continue, then produce the draft according to the recommended solution type. Do not block document drafting in order to confirm every question item by item.
• If the answer can be found from the codebase, existing documents, API documentation, database table schemas, logs, or ADRs, verify it first; do not ask the user directly.
• Advance the decision tree in dependency order: business goals → affected systems → data model and SQL schema → core flow → key difficulties and pseudocode → interfaces → distributed/high concurrency/consistency/idempotency → compatibility → testing → launch → observability → risks.
• When the user uses vague or overloaded terms such as "account", "order", "status", "callback", "compensation", "asynchronous", or "canary", classify them by impact scope: those affecting the core path are P0, and those affecting local fields or wording are P1/P2.
• When the behavior described by the user conflicts with the code or documentation, immediately point out the conflict as P0 and ask which source is more authoritative.
• Continuously maintain a list of unresolved issues; do not lose it as the conversation progresses.

2. Synthesis Mode

When the current conversation, PRD, codebase, and documentation already provide enough information, use synthesis mode, but do not draft the solution directly. First briefly restate the information already grasped and the recommended solution type to the user, give the user one chance to correct it, and then enter the corresponding template for drafting.

• Before drafting, do an "information playback": requirement goals, success criteria for this phase, non-goals for this phase, recommended solution type, known materials, involved systems/code repositories, core path, key constraints, confirmed facts, recommended assumptions, and questions pending confirmation.
• The information playback should be concise, focusing on calibrating understanding; do not expand it into the main body of the solution in advance.
• The information playback must distinguish "confirmed facts", "recommended assumptions", and "questions pending confirmation". If the user replies "continue with all recommendations", directly draft the document according to the recommended solution type.
• Do not repeatedly interview for non-blocking details. Make explicit assumptions about unknown information and record them in Issue Log。
• If the solution depends on the current state of the code, explore the codebase before drafting.
• If there is CONTEXT.md / CONTEXT-MAP.md, use the project domain vocabulary in it.
• Respect relevant ADRs. If an ADR has already constrained boundaries, technology choices, or integration methods, do not easily propose an opposing solution.
• Split the implementation into modules with stable responsibilities. Prioritize identifying deep modules: simple external interfaces, carrying more behavior internally, and independently testable.
• Produce a finished document matching the solution type; do not provide only a loose outline.

Codebase and Documentation Awareness

Before asking the user about architecture or current behavior, look for local evidence first:

• CONTEXT-MAP.md: used to identify multi-context repositories.
• In the root directory or context directory's CONTEXT.md: used to confirm the canonical domain language.
• docs/adr/: used to confirm existing technical decisions.
• Existing interface documentation, schema, database migrations, configuration, controller, service, client, tests, and deployment scripts.
• Existing implementations of similar flows or adjacent business.

If there is no CONTEXT.md, do not proactively create it, unless you are currently working with the user to resolve domain terminology issues. If a term has already been clarified and will continue to affect the solution later, follow CONTEXT-FORMAT.md to create or update CONTEXT.md。

Propose ADRs cautiously. Only suggest creating an ADR when all three of the following conditions are met:

1. The decision is difficult to reverse.
2. Without context, future readers would wonder why it was done this way.
3. This is the result of a real trade-off, not an obvious choice.

When writing an ADR, use ADR-FORMAT.md。

Solution Design Principles

Prefer the Minimal Implementable Solution

• Prioritize giving the minimal implementable solution that can satisfy the current need.
• Do not design extensibility in advance, and do not introduce configuration, abstraction, state machines, task systems, or table structures for future possibilities.
• If a simpler solution exists, first explain whether it is feasible; if it is not adopted, explain why it cannot satisfy the current need.
• If a complex solution is more reasonable, you must explain where the complexity comes from, such as consistency, compatibility, performance, auditing, security, or cross-system release constraints.
• Do not use "it might be used in the future" as a design rationale for this iteration. Subsequent evolution can be written into non-goals or issue records.

Change Scope Constraints

• Every change point must be traceable to a clear requirement point, acceptance criterion, or risk control objective.
• Do not do incidental refactoring, do not change unrelated modules, and do not adjust unrelated formatting, naming, or comments.
• When unrelated issues are found, only record them in Issue Records, and do not incorporate them into this iteration's solution.
• When multiple repositories are involved, list the necessary changes by repository; changes whose necessity cannot be explained should be removed from the solution.

Quality Gates

Quality gates are a risk scan checklist, not a checklist to expand in the main text. All solutions must be scanned first; L0/L1 only expand the risk dimensions that are hit, while L2/L3 expand item by item according to the complete template. Do not force long paragraphs for dimensions that are not hit; they may be omitted, or explained in one sentence as "not involved, because...".

• Business Fit: What problem does it solve, who is it for, and what is out of scope for this iteration?
• Upfront Calibration: Does it explain the requirement goals, success criteria for this iteration, non-goals for this iteration, confirmed facts, recommended assumptions, open questions, and the trade-offs among multiple interpretations?
• Solution Type: Does it explain the basis for recommending L0/L1/L2/L3? Has the upgrade trigger condition been checked?
• Requirement Breakdown: What are the sub-requirements, boundaries, dependencies, and edge cases? L0/L1 can be merged into the goals, change details, or acceptance criteria, and do not need a separate chapter.
• Solution Minimization: Is the minimal implementable solution prioritized? If a complex solution is adopted, does it explain why the simple solution is insufficient?
• Change Scope: Can each change point be traced back to a requirement point or risk control objective? Have unrelated refactoring and irrelevant changes been excluded?
• System Impact: Are upstream and downstream systems, application boundaries, and data flows explained? For L2/L3, is a high-level system relationship diagram used first, followed by an itemized list of application/module, interface, task, message, cache, database, configuration, permission, monitoring, release, and rollback impacts?
• Code Repository Changes: When multiple projects or code repositories are involved, are the changed modules, main changes, interdependencies, release order, and verification methods listed for each repository/project?
• Core Flow: What are the normal path, failure path, retry path, and compensation path respectively?
• Data Design: Which tables, models, fields, states, and indexes are added or modified? When database table modifications are involved, are the DDL, indexes, initialization SQL, migration/backfill SQL, rollback SQL, and compatible read/write strategy fully listed? If not applicable, L0/L1 do not expand on this.
• Interface Contract: What changes are there to HTTP, RPC, events, messages, or scheduled tasks? Do they include requests, responses, error codes, idempotency fields, and compatibility strategies? If not applicable, L0/L1 do not expand on this.
• Consistency: Where are transactions, eventual consistency, deduplication, locking, or ordering guarantees needed?
• Key Difficulties: Are key algorithms, state transitions, idempotency checks, compensation flows, or complex branches clearly expressed using pseudocode in a Java 8-compatible style?
• Distributed Systems and High Concurrency: Has multi-instance deployment, concurrent requests, duplicate messages, distributed locks, cache consistency, rate limiting and degradation, hot data, and failure retries been scanned? When risks are identified, are mitigation strategies expanded?
• Concurrency Handling: What happens with duplicate clicks, duplicate callbacks, retries, parallel tasks, and race condition updates?
• Data Volume and Performance: What is the estimated data scale? Which queries or calls may become hotspots?
• Compatibility: Which old behaviors must remain available? Which clients, versions, configurations, or downstream systems will be affected?
• Security and Permissions: Does it involve authentication, data permissions, privacy, auditing, or risk control constraints?
• Test Plan: Which externally observable behaviors require unit tests, integration tests, regression tests, contract tests, or manual verification?
• Release Plan: How are the release order, configuration switches, data initialization, canary release, rollback, and release verification designed?
• Operations Plan: Which metrics, logs, alerts, dashboards, inspections, contingency plans, and manual recovery steps are needed?
• Risk Identification: What is most likely to fail? How will the team detect and handle it?

Document Templates

Select a template based on the recommended solution type. L0/L1 focus on solution details and retain only "Objectives, Solution Details, Acceptance and Release, Issue Log"; modules such as background, staffing, operations, and architecture diagrams are omitted by default. L2/L3 use the complete 9-chapter structure, with first-level headings unchanged.

L0 Delivery Execution Sheet

Used for delivery tasks where requirements are very clear, there are no significant technical trade-offs, and there are no upgrade trigger conditions.

# 一、目标与验收

**需求目标：** {一句话说明本次要交付什么}

**验收口径：**
- {可被产品/测试/业务验证的结果}

# 二、方案细节

**改动明细：**

| 改动项 | 当前情况 | 目标结果 | 具体做法 | 验证方式 |
| --- | --- | --- | --- | --- |
| {页面/接口/配置/脚本/文档/代码模块} | {现状} | {交付后结果} | {具体怎么改} | {如何验证} |

**执行步骤：**

1. {步骤 1}
2. {步骤 2}
3. {步骤 3}

**关键约束：** {没有则省略；例如配置值、开关、输入输出、数据处理边界}

# 三、测试与上线

**测试范围：**
- {测试点}

**上线方式：**
- {发布/配置/脚本执行方式}

**回滚方式：**
- {如何回滚；如果不需要，说明原因}

# 四、问题记录

| 问题 | 当前判断/推荐答案 | 状态 | 负责人 |
| --- | --- | --- | --- |
| {问题} | {推荐答案或假设} | 待确认/已确认 | {负责人} |

L1 Lightweight Technical Solution

For local changes to a single system or single module. Do not introduce complete architecture diagrams, pseudocode, SQL, stress testing, or other sections unless the risk scan hits.

# 一、目标与范围

**PRD/需求来源：** {链接或“暂无”}

**目标：** {1-3 句话说明本次要交付什么}

**范围边界：** {只写本期关键边界；没有则省略}

**推荐方案类型：** L1 轻量技术方案，原因：{判断依据}

# 二、方案细节

**改动明细：**

| 影响对象 | 当前行为 | 目标行为 | 具体做法 | 验收口径 |
| --- | --- | --- | --- | --- |
| {模块/接口/页面/配置/数据项} | {现状} | {目标} | {具体怎么改} | {可验证结果} |

**核心流程：**
{用步骤说明正常路径和必要异常路径；如有复杂分支再补 Mermaid。}

**涉及项设计：**
- 数据：{只写新增/修改/读取规则；不涉及则省略}
- 接口：{只写接口、字段、错误码、兼容点；不涉及则省略}
- 配置：{只写配置项、默认值、开关策略；不涉及则省略}
- 任务/消息：{只写触发、重试、幂等、补偿；不涉及则省略}

# 三、测试与上线

**测试重点：**
- {测试点}

**上线方式：**
- {发布顺序、配置、验收}

**回滚方式：**
- {回滚动作或“不涉及，原因是...”}

# 四、问题记录

| 问题 | 当前判断/推荐答案 | 状态 | 负责人 |
| --- | --- | --- | --- |
| {问题} | {推荐答案或假设} | 待确认/已确认 | {负责人} |

L2 Standard Technical Proposal / L3 In-Depth Review Proposal

L2 uses the complete structure below. On the basis of L2, L3 must strengthen the ADR/trade-off background, capacity and stress testing, monitoring and alerting, emergency response plans, manual recovery, and cross-team release coordination.

# 一、修改历史

| 版本 | 变更日期 | 变更人 | 变更内容 |
| --- | --- | --- | --- |
| v0.1 | YYYY-MM-DD | {姓名/角色} | 初稿 |

# 二、项目背景

**PRD：** {PRD 链接或“暂无”}

**接口文档：** {接口文档链接或“暂无”}

**背景说明：**
{说明业务背景、现状问题、目标用户/业务方、为什么现在要做。}

**目标：**
- {目标 1}
- {目标 2}

**非目标：**
- {本期不做的事项}

# 三、需求细分

| 需求点 | 说明 | 优先级 | 依赖/约束 | 验收口径 |
| --- | --- | --- | --- | --- |
| {需求点} | {说明} | P0/P1/P2 | {依赖或约束} | {可验证结果} |

**边界与场景：**
- 正常场景：{...}
- 异常场景：{...}
- 兼容场景：{...}

# 四、方案设计

## 1. 方案一(主)

### 方案概述
{用几段话说明整体思路、涉及系统、关键链路、主要取舍。}

### 方案取舍与最小化说明
{说明为什么当前方案是最小可落地方案；如果没有采用更简单方案，说明原因；如果没有采用更复杂方案，说明不做的原因。}

### 系统影响范围
{先说明本次变更的系统边界、上下游依赖、是否影响存量链路。不要只写服务名。}

| 影响对象 | 类型 | 影响方式 | 具体变化 | 兼容/迁移策略 | 验证方式 | 负责人 | 风险等级 |
| --- | --- | --- | --- | --- | --- | --- | --- |
| {系统/模块/资源} | 应用/模块/接口/任务/消息/缓存/数据库/配置/权限/监控/发布 | 新增/修改/依赖/废弃/无影响 | {具体影响} | {兼容、灰度、回滚、迁移或“不涉及”} | {单测/联调/回归/观测项} | {负责人} | 高/中/低 |

### 代码仓库改动清单
{涉及多个工程或代码仓库时必须填写；单工程也写一行。若无代码改动，写“不涉及”。仓库名未知时写当前假设，并同步记录到 **九、问题记录**。}

| 代码仓库/工程 | 所属系统/应用 | 改动模块 | 改动类型 | 主要改动 | 依赖/联动仓库 | 发布顺序 | 验证方式 | 负责人 |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| {repo/project} | {系统/应用} | {模块/包/目录或“不涉及”} | 新增/修改/删除/配置/脚本/无代码改动 | {具体改动点} | {依赖的 repo/project 或“不涉及”} | 第 1/2/3 步或“不限制” | {单测/集成/联调/回归/观测项} | {负责人} |

### 流程设计
{先给出高维度整体架构图，再给出核心业务流程。若目标文档平台不支持 Mermaid，说明需要转成图片贴入。}

#### 1. 整体架构图
{用 Mermaid flowchart 表达系统、模块、上下游、存储、缓存、消息和外部依赖之间的关系，帮助评审者先理解系统边界。}

```mermaid
flowchart LR
    User[用户/业务方] --> Entry[入口系统/页面/接口]
    Entry --> Core[核心服务/领域模块]
    Core --> DB[(数据库)]
    Core --> Cache[(缓存)]
    Core --> MQ[[消息/任务]]
    Core --> External[外部系统]
```

#### 2. 核心业务流程
{用 Mermaid sequenceDiagram / flowchart 表达正常路径、关键分支、失败路径、重试路径和补偿路径。}

```mermaid
sequenceDiagram
    participant User as 用户/业务方
    participant Entry as 入口系统
    participant Core as 核心服务
    participant Store as 存储/外部依赖
    User->>Entry: 发起请求/操作
    Entry->>Core: 参数校验与业务调用
    Core->>Store: 读写数据或调用依赖
    Store-->>Core: 返回结果
    Core-->>Entry: 业务处理结果
    Entry-->>User: 返回响应/状态
```

### 模型与表结构设计
{说明新增/变更表、字段、索引、状态流转、数据迁移/回填。若涉及库表修改，必须重点罗列 SQL schema 和关键 SQL，不能只用文字概括。}

```sql
-- 1. 新增表 / 修改表结构
CREATE TABLE / ALTER TABLE ...

-- 2. 索引与唯一约束
CREATE INDEX / CREATE UNIQUE INDEX ...

-- 3. 初始化数据
INSERT INTO ...

-- 4. 数据迁移 / 回填
UPDATE ... / INSERT INTO ... SELECT ...

-- 5. 回滚 SQL
ALTER TABLE ... / DROP INDEX ... / DELETE FROM ...
```

### 重点难点与伪代码
{对关键算法、复杂状态流转、幂等判断、补偿流程、并发控制或核心分支给出 Java 8 风格伪代码。伪代码要表达主要判断、事务边界、锁释放、异常处理和数据写入顺序，不需要贴真实业务代码。}

```java
public class CoreFlowService {

    public Result handleCoreFlow(Request request) {
        validateRequest(request);

        String idempotencyKey = buildIdempotencyKey(request);
        Optional<Result> processedResult = idempotencyRepository.findResult(idempotencyKey);
        if (processedResult.isPresent()) {
            return processedResult.get();
        }

        LockResult lockResult = lockService.tryLock(idempotencyKey, 10, TimeUnit.SECONDS);
        if (!lockResult.isSuccess()) {
            return Result.pending("request is processing");
        }

        try {
            return transactionTemplate.execute(status -> {
                BizRecord record = bizRepository.selectForUpdate(request.getBizId());
                if (!record.canProcess()) {
                    return Result.fail("invalid state");
                }

                record.markProcessing();
                bizRepository.update(record);

                OutboxEvent event = OutboxEvent.create(record.getId(), EventType.BIZ_PROCESSING);
                outboxRepository.insert(event);

                Result result = Result.success(record.getId());
                idempotencyRepository.saveResult(idempotencyKey, result);
                return result;
            });
        } catch (RetryableException ex) {
            retryTaskRepository.insert(RetryTask.from(request, ex));
            return Result.pending("retry later");
        } finally {
            lockService.unlock(lockResult);
        }
    }
}
```

### 接口设计
{列出 HTTP、RPC、MQ/Event、定时任务等契约。包含入参、出参、错误码、幂等字段、兼容策略。}

### 幂等、并发与一致性
{说明重复请求、重复回调、并发更新、事务边界、锁、去重、重试、补偿。所有方案都要按分布式、高并发、多实例部署场景审视，明确是否需要唯一索引、乐观锁、分布式锁、消息去重、顺序消费、限流、降级、熔断和缓存一致性策略。}

### 数据量、性能与扩展性
{说明预估量级、热点路径、缓存、分页、批处理、限流、降级。}

### 原有逻辑兼容
{说明对现有业务、历史数据、老客户端、旧接口、配置开关的影响。若暂无，写“暂无”。}

### 方案优缺点与取舍
| 方案 | 优点 | 缺点 | 结论 |
| --- | --- | --- | --- |
| 方案一 | {...} | {...} | 主方案 |

### 接口文档
```plaintext
1. HTTP: {method} {path}【{接口说明}】
   param:
     {name} {type} {required} {description}
   result:
     {示例 JSON}

2. RPC: {interface}#{method}
   dependency:
     {依赖包/版本}
   param:
     {name} {type} {required} {description}
   result:
     {示例 JSON}
```

# 五、人力安排

| 目标 | 内容 | 时间安排 | 负责人 |
| --- | --- | --- | --- |
| {目标} | {任务内容} | {起止时间/deadline} | {负责人} |

# 六、测试方案

| 测试类型 | 测试重点 | 覆盖范围 | 责任人 |
| --- | --- | --- | --- |
| 单元测试 | {外部可观察行为，不测实现细节} | {模块/能力} | {负责人} |
| 集成/联调测试 | {跨系统链路} | {系统/接口} | {负责人} |
| 回归测试 | {历史逻辑兼容} | {业务范围} | {负责人} |
| 异常测试 | {失败、重试、并发、幂等} | {场景} | {负责人} |

# 七、上线方案

{说明发布顺序、配置变更、数据库变更、数据初始化、灰度策略、回滚策略、发布时间点。}

## 上线ToDo

- [ ] {发布前检查项}
- [ ] {配置/脚本/数据准备}
- [ ] {联调或验收确认}

## 上线观察项

| 观察项 | 指标/日志 | 预期 | 异常处理 |
| --- | --- | --- | --- |
| {观察项} | {metric/log/dashboard} | {预期范围} | {处理方式} |

# 八、运维方案

{说明监控、告警、日志、巡检、手工补偿、数据修复、应急联系人。}

# 九、问题记录

| 问题 | 当前判断/推荐答案 | 状态 | 负责人 |
| --- | --- | --- | --- |
| {问题} | {推荐答案或假设} | 待确认/已确认 | {负责人} |

Self-Check Before Proposal Output

Before outputting the final proposal, first self-check and revise the document according to the checklist below. Unless the user requests it, there is no need to output the self-check process in full.

• Whether there are unstated assumptions.
• Whether the recommended proposal type is stated, and why it was not upgraded or downgraded.
• Whether there is any design beyond the scope of the requirements.
• Whether each newly added table, interface, task, and configuration is necessary; whether L0/L1 avoids unnecessary section expansion.
• Whether each changed repository has a verification method; if cross-repository is involved, whether it has been upgraded to L2/L3 or the reason for lightweight output is stated.
• Whether L2/L3 distinguishes the primary proposal, alternative proposals, and rejected proposals; whether L0/L1 states why the current execution proposal is sufficient.
• Whether blocking issues have been placed in Issue Log。
• Whether there are incidental refactorings or unrelated changes that cannot be traced back to requirement points.
• Whether it is stated why the current proposal is the minimum viable proposal.

Writing Rules

• Use Chinese by default, unless the project convention explicitly requires another language.
• Initial v0.1 modification history uses the current date by default, unless the user provides another date.
• L0/L1 output must place the main body of text in Proposal Details; background, scope, issue log, and release notes only serve delivery and are not expanded into management-oriented sections.
• Prioritize writing specific judgments, not generalities. Replace "idempotency needs to be considered" with specific idempotency keys, deduplication tables, unique indexes, or retry rules.
• When database table modifications are involved, the SQL schema must be listed as key content, including DDL, field types, default values, indexes, unique constraints, initialization SQL, migration/backfill SQL, and rollback SQL.
• Key points, difficulties, complex state transitions, concurrency control, and compensation logic must use short pseudocode to express the core flow; when these risks are not hit, do not force pseudocode for L0/L1. Pseudocode must conform to Java 8 style: use class/method structures, explicit types,Optional、try/catch/finally, enum or DTO naming; do not use function xxx:, implicit variables, or Python/JavaScript-style syntax.
• All proposals must first scan for distributed and high-concurrency risks, including multi-instance concurrency, duplicate requests, duplicate messages, distributed transactions or eventual consistency, cache consistency, hot data, rate limiting and degradation, and failure recovery; only when risks are hit do they need to be expanded in the main text.
• Do not fabricate facts. Unknown information should be written as assumptions or issues to be confirmed.
• Even when the context is already sufficient, do not immediately output the proposal body. First use a few bullet points to restate the currently known information, the recommended proposal type, and key assumptions, and wait for the user to confirm, correct, or request continuation before drafting the corresponding type of document.
• Proposal design adopts the minimum viable proposal by default. Do not add configuration, abstractions, state machines, task systems, or table structures for future possibilities; when a complex proposal is truly needed, clearly state why the simple proposal is insufficient.
• Every change point must be traceable to a requirement point, acceptance criteria, or risk control objective. Do not include incidental refactoring, unrelated module adjustments, or formatting cleanup in the current plan.
• Do not write specific implementation file paths in the final plan unless the team review truly requires them. Describing modules and interfaces is sufficient; file paths easily become outdated.
• When multiple projects, multiple services, or multiple code repositories are involved, prioritize escalating to L2/L3 and fill in the code repository change list, specifying what each repository changes, which repository it depends on, in what order to release, and how to verify; do not write only generalized descriptions such as "backend transformation" or "frontend adaptation".
• Use diagrams when they improve understanding. For L2/L3 process design, you must first provide a high-level overall architecture diagram, then provide the core business process; for L0/L1, add diagrams only when the textual steps are not clear enough. For draft text, prioritize Mermaid:
  • Use flowchart。
  • for cross-system sequence calls, use sequenceDiagram。
  • for business logic with many branches, use flowchart。
  • for data relationships, use erDiagram or tables.
• The document should have high information density but be scannable. A good plan should allow reviewers to quickly locate issues by section.
• The test plan focuses on externally observable behavior and contracts, and does not test private implementation details.
• If the L2/L3 plan requires participation from product, PM, frontend, client, server, testing, data, or operations, the responsibility division must be reflected in V. Staffing Arrangement ; for L0/L1, the responsible person may be indicated in the change list or release plan.

Interaction Method

When the user starts from a vague requirement, open as follows:

I understand that this time we need to produce a reviewable technical plan for {requirement/project}, focusing on solving {core problem}. To make the plan close to the real code and review criteria, please first send me the PRD/requirement document, interface document, or code repository address; if you do not have them for now, I will proceed based on the current context first.

I will first determine whether this is suitable for an L0 delivery execution ticket, L1 lightweight technical plan, L2 standard technical plan, or L3 in-depth review plan; by default, start with lightweight output, and escalate when risk trigger conditions are met.

I will first divide the points to be confirmed into P0/P1/P2:

• P0 blocking decisions: {1-3 questions that must be confirmed, each with a recommended answer}
• P1 important assumptions: {at most 5-8 questions that can be confirmed in batches, each with a recommended answer}
• P2 non-blocking information: {default assumptions adopted directly}

You can reply "continue with all recommendations", or change only a few of them; for unmodified items, I will proceed to the first draft according to the recommended answers and put them into the "Issue Log".

When the context is already sufficient, first replay the information; do not immediately draft the main body of the plan:

Let me first restate the currently known information to avoid misunderstandings when drafting directly:

1. Requirement objective: {one sentence explaining the problem to be solved}
2. Success criteria for this phase: {business/technical/release acceptance criteria}
3. Recommended plan type: {L0/L1/L2/L3, explaining the basis for the judgment and the escalation trigger check results}
4. Known materials: {PRD/interface document/code repository/existing description}
5. Involved systems/repositories: {systems, modules, code repository list}
6. Core path: {entry point, core processing, data write, downstream dependencies}
7. Confirmed facts: {information from materials or explicitly confirmed by the user}
8. Recommended assumptions: {information that can be advanced based on the recommendation}
9. Items to be confirmed: {blocking points that truly require user confirmation} Please first confirm whether these understandings are accurate; after confirmation, I will draft the document according to the recommended solution type, and unconfirmed information will be placed in the "Issue Log".

When the user requests publishing to Feishu or another document system, first produce a Markdown solution, then use the corresponding document tool to create or update the online document.