decisions

决策记录

概述

此技能会在 docs/decisions.md 中按时间顺序记录重要的项目决策。它会记录重要的架构和设计决策，尤其是涉及权衡取舍的决策，从而永久留存关键选择背后的原因。

何时使用此技能

主动建议（谨慎）： 仅当出现明确且重要的架构选择时，才建议记录决策，例如：

• 在数据库系统之间进行选择（例如，SQLite 与 PostgreSQL）
• 选择主要框架或库
• 决定核心架构模式（例如，单体与微服务、渲染方式）
• 做出会长期影响项目的基础设计选择

不要主动建议记录以下内容：

• 次要实现细节
• 常规编码决策
• 小型重构选择
• 无关紧要的技术选择

手动记录： 用户明确提出以下请求时，记录决策：

• “记录这项决策”
• “将此记录到决策日志中”
• “将此添加到 decisions.md”

记录决策

步骤 1：明确决策

根据对话内容，明确：

• 做出了什么决策
• 为什么需要做出此决策（背景）
• 考虑过哪些备选方案（如适用）
• 评估了哪些关键权衡（如适用）
• 最终选择的理由

步骤 2：确定详细程度

根据决策的复杂程度调整详细程度：

简短（简单决策）：

• 标题和 1-2 句摘要
• 示例：选择一个成熟的库

适中（常见决策）：

• 决策描述
• 简要背景（为什么需要做出此决策）
• 做出的选择

详细（复杂决策）：

• 决策描述
• 背景和动机
• 考虑过的备选方案
• 评估过的关键权衡
• 最终选择的理由

步骤 3：设置条目格式

使用以下格式：

## YYYY-MM-DD: [Decision Title]

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

示例（简短）：

## 2025-10-23: Use httprouter for HTTP routing

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

示例（详细）：

## 2025-10-23: Choose SQLite for primary database

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.

步骤 4：写入文件

1. 检查是否存在 docs/ 目录；如有需要则创建
2. 检查是否存在 docs/decisions.md：
   • 如果不存在，使用以下标头创建文件：

     # Project Decisions
     
     This document records significant architectural and design decisions made throughout the project's development.
     
     

   • 如果文件已存在，则读取当前内容
3. 将新的决策条目追加到文件末尾
4. 确保间距正确（新条目前留一个空行）

步骤 5：向用户确认

记录决策后，简要确认记录的内容。例如：

• “已在 docs/decisions.md 中记录使用 SQLite 的决策”
• “已将路由决策添加到决策日志中”

主动建议模式

在对话中发现重要的架构决策时，建议记录该决策：

This seems like a significant architectural decision. Would you like me to record it in docs/decisions.md?

等待用户确认后再记录。

重要说明

• 始终追加到文件末尾（按时间顺序从最早到最新排列）
• 新条目使用当天日期（YYYY-MM-DD 格式）
• 与现有条目保持格式一致
• 不要为同一项决策创建重复条目
• 如果 docs/ 目录不存在，则创建该目录
• 避免记录对长期架构影响不大的琐碎决策