brief (Nas4146)

🤖 简报

向你的AI编码助手简要介绍一次，并更新所有助手。

______________________________________________________________________

问题

您正在使用Claude Projects、GitHub Copilot和Cursor。您希望它们都遵循项目的惯例：

• ✅ 提交前运行测试
• ✅ 代码更改后更新文档
• ✅ 遵循团队的架构模式

但是手动维护3个以上的指令文件既繁琐又容易出错。

解决方案

pip install ai-brief

# One command updates all your AI assistants
brief update "Run pytest before committing any code"

# ✅ .github/copilot-instructions.md updated
# ✅ CLAUDE.md updated
# ✅ AGENTS.md updated
# ✅ .cursorrules updated

______________________________________________________________________

安装

# CLI only (recommended for most users)
pip install ai-brief

# CLI + MCP server (for AI assistant integration)
pip install 'ai-brief[mcp]'

# Or install from source
git clone https://github.com/Nas4146/brief.git
cd brief
pip install -e .              # CLI only
pip install -e '.[mcp]'       # CLI + MCP

要求： Python 3.9+

依赖项：最小！

• 核心 （始终安装）：

- click>=8.0.0 -CLI框架 - pyyaml>=6.0.0 -配置文件支持 - rich>=13.0.0 -漂亮的终端输出

• 可选的 （仅当您需要MCP时）：

- mcp>=0.1.0 -模型上下文协议支持

安装您需要的东西：

• 只需要CLI？ → pip install ai-brief
• 想要AI助手使用Brief吗？ → pip install 'ai-brief[mcp]'

验证安装

# Check CLI is installed
brief --version
# Output: brief, version 0.1.0

# Check MCP server (if installed with [mcp])
which brief-mcp
# Output: /path/to/brief-mcp (if installed)
#         brief-mcp not found (if not installed)

______________________________________________________________________

快速开始

# 1. Navigate to your project
cd your-project

# 2. Initialize brief (discovers existing instruction files)
brief init
# ╭───────────────────╮
# │ Initializing brief│
# │ your-project      │
# ╰───────────────────╯
# 
# Found 3 instruction files:
# ✓ AGENTS.md
# ✓ CLAUDE.md
# ✓ .github/copilot-instructions.md

# 3. Add an instruction
brief update "Always use async/await for database calls"
# Preview changes with color-coded diffs
# Confirm with y/n

# 4. Validate everything is consistent
brief validate
# ✅ All instruction files are consistent!

# 5. List all instruction files
brief list
# Displays table with files and sizes

______________________________________________________________________

特性

• 🔍 自动发现 -自动查找所有指令文件
• 🧠 上下文感知 -了解你的项目结构和惯例
• ✅ 验证 -确保所有文件的一致性
• 🎯 零配置 -开箱即用，需要时可定制
• 🪶 轻量级 -最小依赖（点击+PyYAML+丰富）
• ✨ 漂亮的UI -具有表格、面板和颜色编码的专业终端输出
• 🔒 防止重复 -模糊匹配防止冗余指令
• 👀 预览模式 -在申请之前，请查看具体的变化
• 🤖 MCP支持 -AI助手可以通过模型上下文协议更新自己的指令

______________________________________________________________________

MCP服务器（可选）

简报包括 可选的 MCP服务器，允许AI助手更新自己的指令文件。

备注：MCP支持是完全可选的。没有它，CLI可以完美工作！

安装

# Install Brief with MCP support
pip install 'ai-brief[mcp]'

配置

添加到Claude桌面配置(~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "brief": {
      "command": "brief-mcp"
    }
  }
}

不使用Brief的人工智能助手？ 跳过此部分！CLI独立工作。

看 docs/MCP_SERVER.md 获取完整的MCP文档。

______________________________________________________________________

支持的文件

Brief会自动发现并更新这些指令文件：

______________________________________________________________________

命令

brief init

在项目中初始化简报。发现现有的指令文件并分析项目结构。

brief init

# Output:
# 🚀 Initializing brief in /Users/you/project
# 📝 Scanning for instruction files...
# ✅ Found 3 instruction file(s):
#    • AGENTS.md
#    • CLAUDE.md
#    • .github/copilot-instructions.md
# 🔍 Analyzing project structure...
#    Languages: Python, TypeScript
#    Frameworks: FastAPI, React
# ✅ Configuration file ready: .brief.yaml

brief update "instruction"

为所有具有上下文感知的文件添加新指令。

brief update "Run tests before committing any code"

# Output:
# 📝 Analyzing project: your-project
# ✨ Updating 3 file(s) with context:
#    Languages: Python
#    Test framework: pytest
# 📊 Adding instruction: "Run tests before committing any code"
#    ✅ AGENTS.md
#    ✅ CLAUDE.md
#    ✅ .github/copilot-instructions.md

brief validate

检查指令文件是否与所有代理文件一致。

两种验证模式：

1. --check-all （默认）：验证所有文件中是否存在核心指令/指导

- 检查一个文件中提到的主题是否涵盖在其他文件中 - 使用模糊匹配-不需要逐字匹配 - 有助于确保没有代理遗漏重要指导

1. --check-latest：验证是否已将最新更新添加到所有文件中

- 查找最近修改的文件 - 检查其他文件中是否存在类似内容 - 跑步后有用 brief update 验证传播的更改

# Check overall consistency (default)
brief validate

# Check only if latest update is in all files
brief validate --check-latest --no-check-all

# Check both
brief validate --check-latest

# Output with issues:
# 🔍 Validating instructions in: your-project
# 📋 Checking 3 file(s)...
# 
#   File                              Status
#   ────────────────────────────────────────
#   AGENTS.md                           ✗
#   CLAUDE.md                           ✓
#   .github/copilot-instructions.md     ✗
#
# ⚠️  Found 2 issue(s):
#   • Recent update in 'CLAUDE.md' may be missing from: AGENTS.md
#   • 'copilot-instructions.md' may be missing guidance on: testing, error handling
#
# ❌ Found inconsistencies

# Output when consistent:
# ✅ All instruction files are consistent!

brief list

列出所有发现的指令文件。

brief list

# Output:
# 📋 Instruction files in: your-project
#    ✅ AGENTS.md (2,456 bytes)
#    ✅ CLAUDE.md (1,832 bytes)
#    ✅ .github/copilot-instructions.md (3,120 bytes)
# 📊 Total: 3 file(s)

______________________________________________________________________

用例

对于独立开发者

无需手动复制粘贴，即可使您的个人AI助手指令在工具之间保持一致。

对于团队

通过将项目惯例烘焙到人工智能工具中，更快地培养新开发人员。

对于开源

通过人工智能助手帮助贡献者了解项目的工作流程。

______________________________________________________________________

项目结构

your-project/
├── AGENTS.md                          # Custom instructions
├── CLAUDE.md                          # Claude instructions
├── .github/
│   └── copilot-instructions.md       # Copilot instructions
├── .cursorrules                       # Cursor instructions
├── .brief.yaml                        # Brief config (optional)
└── src/
    └── ...

______________________________________________________________________

配置（可选）

Brief适用于零配置，但您可以使用自定义行为 .brief.yaml:

version: 1

# Instruction files to manage
instruction_files:
  - AGENTS.md
  - CLAUDE.md
  - .github/copilot-instructions.md
  - .cursorrules

# Project metadata
project:
  languages:
    - Python
    - TypeScript
  frameworks:
    - FastAPI
    - React

# Enabled behaviors (coming soon)
behaviors:
  enabled:
    - test_before_commit
    - update_docs_after_changes

______________________________________________________________________

发展

# Clone the repository
git clone https://github.com/Nas4146/brief.git
cd brief

# Install in development mode with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run linter
ruff check .

# Format code
black .

______________________________________________________________________

路线图

V0.1（当前）-MVP✅ 完成

• ✅ CLI与 init, update, validate, list 命令
• ✅ 自动发现指令文件
• ✅ 上下文感知更新（语言、框架检测）
• ✅ 基本验证
• ✅ 应用更改前的差异预览
• ✅ 用于AI助手集成的MCP服务器
• ✅ 模糊匹配防止重复

V0.2（下一页）

• \[\]具有常见行为的模板库
• \[ \] sync 用于应用模板的命令
• \[\]配置文件生成向导
• \[\]高级一致性检查
• \[\]CI/CD集成示例

V0.3（未来）

• \[\]社区模板市场
• \[\]用于团队管理的Web仪表板
• \[\]Git挂钩集成
• \[\]多项目同步

______________________________________________________________________

贡献

欢迎投稿！请看 贡献.md 作为指导方针。

______________________________________________________________________

许可证

麻省理工学院©2025

______________________________________________________________________

为什么是“简短”？

简报 （动词）： *向某人提供重要信息*

非常适合为您的AI助手提供他们所需的基本上下文，并让它传播到任何地方。

______________________________________________________________________

链接

• GitHub:
• 问题:

______________________________________________________________________