Back to Details

decisions

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Decisions

决策记录

Overview

概述

This skill maintains a chronological record of significant project decisions in 
docs/decisions.md
. It captures important architectural and design decisions, especially those involving tradeoffs, to create a permanent record of why key choices were made.
本技能负责在
docs/decisions.md
中按时间顺序记录项目的重大决策。它会捕获重要的架构与设计决策，尤其是涉及取舍权衡的决策，以此留存关键选择背后的原因，形成永久记录。

When to Use This Skill

何时使用本技能

Proactive (Conservative): Suggest recording decisions only when there is a clearly significant architectural choice, such as:
  • Choosing between database systems (e.g., SQLite vs PostgreSQL)
  • Selecting major frameworks or libraries
  • Deciding on core architectural patterns (e.g., monolith vs microservices, rendering approach)
  • Making fundamental design choices that will shape the project long-term
Do NOT proactively suggest for:
  • Minor implementation details
  • Routine coding decisions
  • Small refactoring choices
  • Trivial technical choices
Manual: Record decisions when explicitly requested by the user with phrases like:
  • "Record this decision"
  • "Document this in the decision log"
  • "Add this to decisions.md"
主动触发（谨慎使用）： 仅当出现明确的重大架构选择时，才建议记录决策，例如：
  • 数据库系统选型（如SQLite与PostgreSQL对比）
  • 主要框架或库的选择
  • 核心架构模式的确定（如单体架构与微服务对比、渲染方案选择）
  • 做出会长期影响项目发展的基础设计选择
请勿主动触发的场景：
  • 次要实现细节
  • 常规编码决策
  • 小型重构选择
  • 无关紧要的技术选择
手动触发： 当用户明确提出如下请求时，记录决策：
  • "记录这个决策"
  • "把这个记录到决策日志中"
  • "添加到decisions.md里"

Recording a Decision

记录决策的步骤

Step 1: Identify the Decision

步骤1：明确决策内容

From the conversation context, identify:
  • What decision was made
  • Why it was needed (context)
  • What alternatives were considered (if applicable)
  • Key tradeoffs evaluated (if applicable)
  • Rationale for the final choice
从对话语境中提取以下信息：
  • 做出了什么决策
  • 决策的背景（为什么需要做这个决策）
  • 考虑过哪些替代方案（如有）
  • 评估过的关键取舍（如有）
  • 最终选择的理由

Step 2: Determine Detail Level

步骤2：确定记录详细程度

Adapt the level of detail based on decision complexity:
Brief (simple decisions):
  • Title and 1-2 sentence summary
  • Example: Choosing a well-established library
Moderate (typical decisions):
  • Decision description
  • Brief context (why it was needed)
  • The choice made
Detailed (complex decisions):
  • Decision description
  • Context and motivation
  • Alternatives considered
  • Key tradeoffs evaluated
  • Rationale for final choice
根据决策的复杂度调整记录的详细程度：
简洁版（简单决策）：
  • 标题加1-2句话的总结
  • 示例：选择一款成熟的库
中等详细版（常规决策）：
  • 决策描述
  • 简要背景（决策的必要性）
  • 最终选择的方案
详细版（复杂决策）：
  • 决策描述
  • 背景与动机
  • 考虑过的替代方案
  • 评估的关键取舍
  • 最终选择的理由

Step 3: Format the Entry

步骤3：格式化条目

Use this format:
markdown
undefined
使用以下格式：
markdown
undefined

YYYY-MM-DD: [Decision Title]

YYYY-MM-DD: [决策标题]

[Description paragraph(s) adapted to the complexity level]

Example (brief):
```markdown
[根据复杂度调整的描述段落]

示例（简洁版）：
```markdown

2025-10-23: Use httprouter for HTTP routing

2025-10-23: 使用httprouter作为HTTP路由工具

Chose httprouter for its simplicity and performance. It's a well-established library that fits our needs without unnecessary complexity.

Example (detailed):
```markdown
选择httprouter是因为它简洁高效，是一款成熟的库，能满足我们的需求且无冗余复杂度。

示例（详细版）：
```markdown

2025-10-23: Choose SQLite for primary database

2025-10-23: 选择SQLite作为主数据库

After evaluating PostgreSQL and SQLite, we chose SQLite for the following reasons:
Context: Need a reliable database for the application that handles moderate traffic (< 1000 concurrent users) and simple relational data.
Alternatives considered:
  • PostgreSQL: More features and better for high concurrency, but adds operational complexity
  • SQLite: Simpler deployment, embedded database, sufficient performance for our scale
Tradeoffs: SQLite has limitations with high write concurrency and some advanced features, but offers zero-configuration deployment and excellent read performance. Given our expected load and preference for operational simplicity, these tradeoffs favor SQLite.
Decision: Use SQLite with WAL mode enabled for improved concurrency. We can migrate to PostgreSQL later if scaling needs change.
undefined
在评估PostgreSQL和SQLite后，我们选择SQLite的原因如下：
背景：需要为应用选择一款可靠的数据库，以处理中等流量（<1000并发用户）和简单的关系型数据。
考虑的替代方案：
  • PostgreSQL：功能更丰富，更适合高并发场景，但增加了运维复杂度
  • SQLite：部署更简单，是嵌入式数据库，性能足以满足我们的规模需求
取舍权衡：SQLite在高写入并发和部分高级功能上存在局限，但无需配置即可部署，且读取性能优异。结合我们预期的负载和对运维简洁性的偏好，这些取舍更倾向于选择SQLite。
决策：启用WAL模式的SQLite作为主数据库。若后续扩展需求变化，可迁移至PostgreSQL。
undefined

Step 4: Write to File

步骤4：写入文件

  1. Check if 
    docs/
    directory exists; create it if needed
  2. Check if 
    docs/decisions.md
    exists:
    • If not, create it with this header:
      markdown
      # Project Decisions

This document records significant architectural and design decisions made throughout the project's development.
    • If it exists, read the current content
  3. Append the new decision entry to the bottom of the file
  4. Ensure proper spacing (blank line before the new entry)
  1. 检查
    docs/
    目录是否存在；若不存在则创建
  2. 检查
    docs/decisions.md
    是否存在：
    • 若不存在，创建文件并添加以下头部内容：
      markdown
      # 项目决策记录

本文档记录了项目开发过程中做出的所有重要架构与设计决策。
    • 若已存在，读取当前内容
  3. 将新的决策条目追加到文件底部
  4. 确保格式正确（新条目前添加空行）

Step 5: Confirm with User

步骤5：向用户确认

After recording the decision, briefly confirm what was recorded. For example:
  • "Recorded the decision to use SQLite in docs/decisions.md"
  • "Added the routing decision to the decision log"
记录完成后，向用户简要确认记录内容。例如：
  • "已在docs/decisions.md中记录选择SQLite的决策"
  • "已将路由决策添加到决策日志中"

Proactive Suggestion Pattern

主动建议模板

When detecting a significant architectural decision during conversation, suggest recording it:
This seems like a significant architectural decision. Would you like me to record it in docs/decisions.md?
Wait for user confirmation before recording.
当对话中出现重大架构决策时，可建议记录：
这看起来是一项重大的架构决策，是否需要我将其记录到docs/decisions.md中？
需等待用户确认后再进行记录。

Important Notes

重要注意事项

  • Always append to the bottom (chronological order from oldest to newest)
  • Use today's date (YYYY-MM-DD format) for new entries
  • Maintain formatting consistency with existing entries
  • Don't create duplicate entries for the same decision
  • Create 
    docs/
    directory if it doesn't exist
  • Avoid recording trivial decisions that don't have long-term architectural impact
  • 始终追加到文件底部（按时间顺序从旧到新排列）
  • 新条目使用当日日期（YYYY-MM-DD格式）
  • 与现有条目保持格式一致
  • 不要为同一决策创建重复条目
  • 若
    docs/
    目录不存在则创建
  • 避免记录对长期架构无影响的琐碎决策