Decision CLI

决策CLI

在人工智能的帮助下跟踪架构决策。按领域组织，管理团队工作流程，与任何MCP客户端无缝集成。

一个全面的CLI工具和MCP服务器，用于管理架构决策记录（ADR）。通过命令行独立工作，或直接与人工智能工具集成，如Claude Code、Codex、Cursor、Windsurf和任何兼容MCP的客户端。

跳到快速设置

关键优势

简洁：使用智能默认值进行零配置初始化 组织：基于域的结构使决策易于发现 工作流程：内置团队审查流程（草案→ 提议→ 接受） 人工智能原生：11个MCP工具使AI代理能够直接管理决策

简单的设置和操作

• 一个命令初始化 - decision init 创造你需要的一切
• 智能身份生成 -具有可自定义前缀的自动顺序ID
• 子目录友好 -从仓库中的任何地方运行，自动查找 .decision/
• Git感知用户身份 -自动检测您的姓名/电子邮件以获得批准

团队工作流支持

• 状态生命周期 -草稿→ 提议→ 接受/拒绝→ 已弃用/被取代
• 审批跟踪 -记录谁批准/拒绝以及何时批准/拒绝
• 关系链接 -连接相关决策，跟踪替代链
• 验证检查 -确保决策在验收前有必要的部分

AI代理集成

• 11个MCP工具 -为AI代理完成CRUD+工作流操作
• 适用于任何MCP客户端 -克劳德密码、Codex、Cursor、Windsurf、Cline等。
• AGENTS.md一代 -自动生成的AI上下文摘要
• 用户身份管理 -AI自动使用的配置审批人

完整功能集

核心决策管理

• 制定决策 使用模板进行交互或编程
• 列表和筛选器 按状态、域或标签
• 搜索 在所有具有相关性评分的决策内容中
• 展示 包含前台和内容的完整决策细节
• 出口 外部工具转换为JSON或HTML

状态工作流

• 提议 -提交草稿供团队审查
• 接受/拒绝 -使用审批人身份记录审批
• 重新开放 -将被拒绝的决定退回起草
• 弃用 -标记过时的决定
• 取代 -用新决策替换旧决策（两者都自动链接）

组织与发现

• 基于域的文件夹 -按区域分组（身份验证、前端、后端等）
• 自定义模板 -包括默认模板和安全模板
• 关系图 -可视化决策连接（ASCII、DOT、JSON）
• Git历史记录 -查看任何决策的更改历史记录

配置与验证

• 可定制的ID格式 - PRJ-0001, ADR-0001等等。
• 域名管理 -动态添加/删除域
• 验证规则 -检查是否有缺失的部分、空白内容
• 格式规范化 -格式一致，差异清晰

______________________________________________________________________

与AI代理合作

Decision CLI旨在实现无缝的AI协作。配置后，您可以让您的AI助手使用自然语言管理决策。

为什么要使用人工智能进行决策管理？

• 更快的文档记录 -AI根据对话上下文起草决策
• 一致格式 -AI自动遵循模板
• 即时搜索 -人工智能在建议更改之前会发现相关决策
• 自动关系 -人工智能在创建相关决策时将其联系起来
• 审查协助 -人工智能在提出建议之前验证决策

自然语言示例

配置MCP服务器后，您只需询问：

制定决策：

"Create a decision to use Redis for caching in the backend domain"

"Document our choice to use TypeScript strict mode"

"Add an architectural decision for the new authentication flow we just discussed"

查询决策：

"What decisions have we made about authentication?"

"Show me all accepted backend decisions"

"Are there any decisions related to caching?"

"List deprecated decisions that might need review"

更新决策：

"Update the JWT decision to include the new refresh token strategy"

"Mark decision 5 as accepted"

"Link the Redis caching decision to the session management decision"

"Deprecate the old MongoDB decision since we switched to PostgreSQL"

工作流管理：

"Propose decision 3 for team review"

"Accept all proposed decisions in the auth domain"

"What decisions are waiting for approval?"

AGENTS.md摘要

这 AGENTS.md 该文件是专门为AI代理设计的特殊摘要。它提供：

即时上下文

• 按领域组织的所有决策的完整目录
• 状态概述（接受、建议、弃用的数量）
• 供快速参考的最新决定

AI优化格式

• 结构化，可通过语言模型快速解析
• 包括决策关系和替代链
• 语义搜索的标签和元数据

始终为最新

• 通过以下方式随时再生 decision summary
• 仅在决策实际发生变化时更新（除非 --force)
• 跟踪上一代时间戳

AI如何使用AGENTS.md

当你向人工智能助理询问你的项目架构时：

1. AI读取 .decision/AGENTS.md 用于完整的决策上下文
2. AI理解做出了什么选择以及为什么
3. 人工智能避免提出与现有决策相矛盾的方法
4. AI在提出变更时参考相关决策

AGENTS.md内容示例：

# Decision Records Summary

> Auto-generated summary for AI agents. Last updated: 2024-01-30T10:30:00Z

## Overview

- **Total Decisions:** 15
- **Accepted:** 12
- **Proposed:** 2
- **Draft:** 1

## By Domain

### auth (3 decisions)
- [PRJ-0001] Use JWT for Authentication (accepted)
- [PRJ-0005] Implement MFA with TOTP (accepted)
- [PRJ-0010] Session Management Strategy (proposed)

### backend (4 decisions)
- [PRJ-0003] Use PostgreSQL for Primary Database (accepted)
- [PRJ-0007] Use Redis for Caching (accepted)
...

## Recent Decisions

1. PRJ-0015: API Versioning Strategy (2024-01-28) - proposed
2. PRJ-0014: Error Handling Standards (2024-01-25) - accepted
...

## Relationships

- PRJ-0010 supersedes PRJ-0001
- PRJ-0007 related to PRJ-0003, PRJ-0010

生成摘要

# Generate/update AGENTS.md
decision summary

# Force regeneration (updates timestamp even if unchanged)
decision summary --force

通过MCP：

{ "name": "decision_summary", "arguments": { "force": true } }

人工智能协作的最佳实践

1. 首先初始化用户身份

   decision user setup

这确保了人工智能创建的审批使用您的真实姓名/电子邮件。

1. 将AGENTS.md保留在版本控制中

该摘要有助于所有团队成员的AI助手保持一致。

1. 提示中的参考决策

“根据PRJ-0003，我们使用PostgreSQL。我们应该如何处理……”

1. 让AI在接受之前进行验证

问：“验证所有拟议的决定并显示任何问题”

1. 始终如一地使用域名

组织良好的领域有助于人工智能更快地找到相关上下文。

______________________________________________________________________

快速设置

先决条件

• Node.js>=20.19.0

安装

使用npx（无需安装）：

npx @aitool/decision-cli init
npx @aitool/decision-cli new
npx @aitool/decision-cli list

全球安装：

npm install -g @aitool/decision-cli

# Now use 'decision' command anywhere
decision init
decision new
decision list

初始化您的项目

# Initialize with auto-detected prefix from package.json
decision init

# Or specify a custom prefix
decision init --prefix ADR

这将创建：

.decision/
├── config.yaml           # Configuration
├── templates/
│   ├── default.md        # Standard template
│   └── security.md       # Security-focused template
└── general/              # Default domain folder

配置用户身份

设置您的身份以获得决策批准：

# Auto-detect from git config
decision user setup

# Or specify manually
decision user setup --name "Your Name" --email "you@example.com"

______________________________________________________________________

CLI使用情况

制定决策

# Interactive mode (prompts for title, domain, template)
decision new

# Non-interactive with options
decision new --title "Use Redis for Caching" --domain backend --no-interactive

列表和查看

# List all decisions
decision list

# Filter by status
decision list --status accepted

# Filter by domain
decision list --domain auth

# Show specific decision (by ID or number)
decision show 1
decision show PRJ-0001

# Search across all decisions
decision search "authentication"

状态工作流

# Submit for review
decision propose 1

# Accept (uses configured user identity)
decision accept 1

# Reject with reason
decision reject 1 --reason "Needs more analysis"

# Reopen rejected decision
decision reopen 1

# Mark as deprecated
decision deprecate 1

# Supersede with new decision
decision supersede 1 2

关系

# Link related decisions
decision link 1 2

# Remove link
decision unlink 1 2

# View relationship graph
decision graph
decision graph --format dot  # For GraphViz

验证和导出

# Validate all decisions
decision validate

# Validate specific decision
decision validate --id 1

# Generate AGENTS.md summary
decision summary

# Export to JSON
decision export --format json --output decisions.json

配置

# Show all config
decision config

# Get specific value
decision config get id-format

# Set value
decision config set default-domain backend

# Add new domain
decision config add-domain infrastructure

# Repair next-id cache
decision config repair

______________________________________________________________________

MCP集成

MCP服务器允许AI工具通过模型上下文协议直接管理决策。

启动MCP服务器

# Global install
decision mcp

# Using npx
npx @aitool/decision-cli mcp

克劳德代码

# Add MCP server (recommended — uses npx, no global install needed)
claude mcp add decision -- npx @aitool/decision-cli mcp

# Or if installed globally
claude mcp add decision -- decision mcp

# Verify it's registered
claude mcp list

# Remove when no longer needed
claude mcp remove decision

一旦添加，只需自然地与克劳德交谈：

You: "Create a decision to use Redis for caching in the backend domain"
You: "What decisions have we made about authentication?"
You: "Mark decision 3 as accepted"

食品法典委员会（OpenAI）

# Add MCP server
codex mcp add decision -- npx @aitool/decision-cli mcp

# Or if installed globally
codex mcp add decision -- decision mcp

# Verify
codex mcp list

然后在Codex会议中自然使用：

You: "List all accepted decisions in the auth domain"
You: "Create a decision for the new authentication flow"

克劳德桌面

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "decision": {
      "command": "npx",
      "args": ["@aitool/decision-cli", "mcp"],
      "cwd": "/path/to/your/project"
    }
  }
}

或者，如果全局安装：

{
  "mcpServers": {
    "decision": {
      "command": "decision",
      "args": ["mcp"]
    }
  }
}

Cursor/Windsurf/Cline/其他MCP客户端

大多数MCP客户端使用相同的JSON配置格式。添加到MCP设置中：

{
  "mcpServers": {
    "decision": {
      "command": "npx",
      "args": ["@aitool/decision-cli", "mcp"],
      "cwd": "/path/to/your/project"
    }
  }
}

任何MCP客户端的关键设置：

• 命令: npx （或 decision 如果全局安装）
• 参数: ["@aitool/decision-cli", "mcp"] （或 ["mcp"] 如果是全局）
• 当前工作目录：您的项目根（其中 .decision/ 存在或应创建）

可用的MCP工具

MCP工具示例

列出已接受的决定：

{ "name": "decision_list", "arguments": { "status": "accepted" } }

创建新决策：

{
  "name": "decision_create",
  "arguments": {
    "title": "Use PostgreSQL for Primary Database",
    "domain": "backend",
    "content": "## Context\n\nWe need a reliable relational database...\n\n## Decision\n\nUse PostgreSQL...\n\n## Consequences\n\n### Positive\n- ACID compliance..."
  }
}

接受决定（使用配置的用户身份）：

{ "name": "decision_status", "arguments": { "id": "1", "status": "accepted" } }

______________________________________________________________________

决策记录格式

决策存储为带有YAML frontmatter的Markdown文件：

---
id: PRJ-0001
title: Use JWT for Authentication
status: accepted
date: 2024-01-28
domain: auth
deciders: [john, sarah]
tags: [security, api]
related: [PRJ-0003]
approved-by: [John Doe ]
approved-date: 2024-01-30
---

## Context

Our API needs stateless authentication for horizontal scaling...

## Decision

We will use JWT tokens with RS256 signing algorithm...

## Consequences

### Positive

- Stateless authentication scales horizontally
- No session storage required

### Negative

- Token revocation requires deny-list implementation

决策生命周期

draft → proposed → accepted → [deprecated | superseded]
              ↘ rejected → draft (reopen)

______________________________________________________________________

文件夹结构

.decision/
├── config.yaml           # Project configuration
├── user.yaml             # User identity (git-ignored)
├── AGENTS.md             # Auto-generated AI summary
├── templates/
│   ├── default.md        # Standard template
│   └── security.md       # Security template
├── auth/                 # Domain: auth
│   ├── PRJ-0001-jwt-auth.md
│   └── PRJ-0005-mfa.md
├── frontend/             # Domain: frontend
│   └── PRJ-0002-use-react.md
├── backend/              # Domain: backend
│   └── PRJ-0003-use-postgres.md
└── general/              # Default domain
    └── PRJ-0004-coding-standards.md

______________________________________________________________________

配置参考

.decision/config.yaml:

version: 1
project-name: my-project
id-format: "PRJ-{number}"
id-padding: 4
domains:
  - auth
  - frontend
  - backend
  - general
default-domain: general
templates:
  default: templates/default.md
  security: templates/security.md
domain-templates:
  auth: security
summary:
  auto-generate: false
  include-insights: true
  include-recent: 5

配置选项

______________________________________________________________________

发展

npm install
npm run build
node bin/decision.js --help

npm run build        # Build TypeScript
npm run dev          # Watch mode
npm test             # Run tests
npm run test:watch   # Tests in watch mode
npm run lint         # Lint code
npm run check        # Lint + type check

本地测试

npm link
decision --help      # Now available globally
npm unlink -g @aitool/decision-cli  # When done

______________________________________________________________________

许可证

麻省理工学院-见 许可证

由...创建 库尔丁