重要前提
安装AI Skills的关键前提是:必须科学上网,且开启TUN模式,这一点至关重要,直接决定安装能否顺利完成,在此郑重提醒三遍:科学上网,科学上网,科学上网。查看完整安装教程 →
npx skills add https://github.com/patricio0312rev/skills --skill adr-writer通过清晰的背景、备选方案和影响来记录架构决策。
# ADR-001: [决策标题]
**状态:** 提议中 | 已采纳 | 已弃用 | 被 ADR-XXX 取代
**日期:** 2024-01-15
**决策者:** Alice (技术负责人), Bob (首席工程师)
**负责人:** Alice
## 背景
我们面临什么问题?哪些因素驱动着这项决策?
我们需要为新的分析服务选择一个数据库。当前需求:
- 每天超过 1000 万事件
- 复杂的聚合查询
- 实时仪表板
- 预算:每月 5000 美元
- 团队熟悉 SQL
## 决策
我们将使用带有 TimescaleDB 扩展的 PostgreSQL。
## 考虑的备选方案
### 方案 1: PostgreSQL + TimescaleDB (已选择)
**优点:**
- 团队已经了解 PostgreSQL
- 针对分析的时间序列优化
- 可靠且经过验证
- 良好的查询性能
- 合理的成本 (~每月 3000 美元)
**缺点:**
- 需要手动扩展工作
- 并非专为分析构建
### 方案 2: ClickHouse
**优点:**
- 针对分析工作负载的卓越查询性能
- 专为分析工作负载构建
- 列式存储
**缺点:**
- 团队不熟悉 ClickHouse
- 学习曲线更陡峭
- 不同的查询语法
### 方案 3: BigQuery
**优点:**
- 完全托管
- 非常适合分析
- 自动扩展
**缺点:**
- 成本更高 (按我们的量级约每月 8000 美元)
- 供应商锁定于 GCP
- 对优化的控制较少
## 权衡取舍
**我们优先考虑的是:**
- 团队效率 (熟悉的技术)
- 成本效益
- 足够好的性能
**我们牺牲的是:**
- 峰值分析性能 (相比 ClickHouse)
- 完全托管的体验 (相比 BigQuery)
## 影响
### 积极影响
- 可以立即开始开发 (无学习曲线)
- 较低的运营成本
- 可以复用现有的 PostgreSQL 专业知识
- 易于与当前技术栈集成
### 消极影响
- 需要手动优化查询
- 如果规模扩大 10 倍,可能需要重新评估
- 比 BigQuery 需要更多的运维工作
### 风险
- 在每天超过 1 亿事件时性能可能下降
- **缓解措施:** 监控查询性能,在每天 5000 万事件时规划迁移
## 实施说明
- 使用 TimescaleDB 超表存储事件
- 为常见查询实现连续聚合
- 为仪表板查询设置只读副本
- 在每天 5000 万事件时记录扩展手册
## 后续行动
- [ ] 配置 PostgreSQL + TimescaleDB 集群 (Alice, 截止 2024-01-20)
- [ ] 创建从 MySQL 迁移的脚本 (Bob, 截止 2024-01-22)
- [ ] 设置监控仪表板 (Alice, 截止 2024-01-25)
- [ ] 记录扩展阈值 (Alice, 截止 2024-01-30)
## 参考资料
- [TimescaleDB 基准测试](https://example.com)
- [成本分析电子表格](https://docs.google.com/...)
- [团队调查结果](https://example.com)
## 修订历史
- 2024-01-15: 初始草案 (Alice)
- 2024-01-16: 添加成本分析 (Bob)
- 2024-01-17: 被架构评审委员会采纳
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
ADR-001: 初始系统架构
ADR-002: 分析数据库选择
ADR-003: 认证策略
...
提议中 → 已采纳 → 已实施
↓
已拒绝
已采纳 → 已弃用 → 被 ADR-XXX 取代
技术选型:
架构模式:
基础设施:
安全:
# 1. 创建新的 ADR
cp templates/adr-template.md docs/adr/ADR-042-title.md
# 2. 填写各章节
# - 背景: 我们为什么做出这个决策?
# - 决策: 我们决定了什么?
# - 备选方案: 我们还考虑了哪些方案?
# - 影响: 会产生什么影响?
# 3. 与团队评审
# - 在架构频道分享
# - 获取利益相关者的反馈
# - 迭代备选方案
# 4. 将状态更新为“已采纳”
# 5. 从主架构文档链接
❌ 过于详细 : 没人会读的 10 页 ADR ❌ 没有备选方案 : 看起来决策是预先确定的 ❌ 缺少影响分析 : 忽视缺点 ❌ 没有负责人 : 无人负责 ❌ 状态过时 : 旧的 ADR 仍标记为“提议中”
每周安装数
54
代码仓库
GitHub 星标数
20
首次出现
2026年1月24日
安全审计
安装于
codex44
opencode43
github-copilot43
gemini-cli42
cursor40
claude-code38
Document architecture decisions with clear context, alternatives, and consequences.
# ADR-001: [Title of Decision]
**Status:** Proposed | Accepted | Deprecated | Superseded by ADR-XXX
**Date:** 2024-01-15
**Deciders:** Alice (Tech Lead), Bob (Principal Engineer)
**Owner:** Alice
## Context
What is the issue we're facing? What factors are driving this decision?
We need to choose a database for our new analytics service. Current
requirements:
- 10M+ events per day
- Complex aggregation queries
- Real-time dashboards
- Budget: $5k/month
- Team familiar with SQL
## Decision
We will use PostgreSQL with TimescaleDB extension.
## Alternatives Considered
### Option 1: PostgreSQL + TimescaleDB (CHOSEN)
**Pros:**
- Team already knows PostgreSQL
- Time-series optimization for analytics
- Reliable and proven
- Good query performance
- Reasonable cost (~$3k/month)
**Cons:**
- Requires manual scaling effort
- Not purpose-built for analytics
### Option 2: ClickHouse
**Pros:**
- Excellent query performance for analytics
- Built for analytics workloads
- Column-oriented storage
**Cons:**
- Team unfamiliar with ClickHouse
- Steeper learning curve
- Different query syntax
### Option 3: BigQuery
**Pros:**
- Fully managed
- Excellent for analytics
- Scales automatically
**Cons:**
- Higher cost (~$8k/month for our volume)
- Vendor lock-in to GCP
- Less control over optimization
## Tradeoffs
**What we're optimizing for:**
- Team velocity (familiar tech)
- Cost efficiency
- Good enough performance
**What we're sacrificing:**
- Peak analytical performance (vs ClickHouse)
- Fully managed experience (vs BigQuery)
## Consequences
### Positive
- Development can start immediately (no learning curve)
- Lower operational costs
- Can reuse existing PostgreSQL expertise
- Easy integration with current stack
### Negative
- Will need to manually optimize queries
- May need to revisit if we scale 10x
- Requires more operational work than BigQuery
### Risks
- Performance may degrade at 100M+ events/day
- **Mitigation:** Monitor query performance, plan migration at 50M events/day
## Implementation Notes
- Use TimescaleDB hypertables for event storage
- Implement continuous aggregates for common queries
- Set up read replicas for dashboard queries
- Document scaling runbook at 50M events/day
## Follow-up Actions
- [ ] Provision PostgreSQL + TimescaleDB cluster (Alice, by 2024-01-20)
- [ ] Create migration script from MySQL (Bob, by 2024-01-22)
- [ ] Set up monitoring dashboards (Alice, by 2024-01-25)
- [ ] Document scaling thresholds (Alice, by 2024-01-30)
## References
- [TimescaleDB Benchmarks](https://example.com)
- [Cost Analysis Spreadsheet](https://docs.google.com/...)
- [Team Survey Results](https://example.com)
## Revision History
- 2024-01-15: Initial draft (Alice)
- 2024-01-16: Added cost analysis (Bob)
- 2024-01-17: Accepted by architecture review board
ADR-001: Initial System Architecture
ADR-002: Database Selection for Analytics
ADR-003: Authentication Strategy
...
Proposed → Accepted → Implemented
↓
Rejected
Accepted → Deprecated → Superseded by ADR-XXX
Technology Selection:
Architecture Patterns:
Infrastructure:
Security:
# 1. Create new ADR
cp templates/adr-template.md docs/adr/ADR-042-title.md
# 2. Fill in sections
# - Context: Why are we making this decision?
# - Decision: What did we decide?
# - Alternatives: What else did we consider?
# - Consequences: What are the impacts?
# 3. Review with team
# - Share in architecture channel
# - Get feedback from stakeholders
# - Iterate on alternatives
# 4. Update status to "Accepted"
# 5. Link from main architecture docs
❌ Too detailed : 10-page ADRs nobody reads ❌ No alternatives : Looks like decision was predetermined ❌ Missing consequences : Ignoring downsides ❌ No owner : Nobody accountable ❌ Outdated status : Old ADRs marked "Proposed"
Weekly Installs
54
Repository
GitHub Stars
20
First Seen
Jan 24, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykPass
Installed on
codex44
opencode43
github-copilot43
gemini-cli42
cursor40
claude-code38
论文复现上下文解析器 - 解决AI论文复现中的关键信息缺口与冲突检测
28,400 周安装
Go数据库模式指南:database/sql、sqlx、pgx与仓库模式实践
177 周安装
Bitbucket工作流最佳实践:拉取请求、Pipelines CI/CD与Jira集成完整指南
174 周安装
专业市场研究报告生成工具 - 50+页咨询级行业分析,含PESTLE、SWOT、波特五力等框架
171 周安装
表单验证最佳实践:React Hook Form、TypeScript与Vue VeeValidate完整指南
170 周安装
竞争分析师智能体:系统性竞争对手分析、市场定位评估与战略优势识别
170 周安装
ADHD/自闭症任务拆解指南:DECOMPOSE方法助你克服执行功能障碍,提升生产力
187 周安装