briefbrief

无论是新贡献者、安全扫描器，还是 AI 编程代理，只要进入一个不熟悉的代码库，在开展任何有用工作之前，都必须回答几个关键问题：这是什么语言？如何安装依赖项？测试命令是什么？提交前需要运行哪个代码检查工具？如果是安全审查，该栈中哪些函数是危险的？

代理的情况最容易观察到出错的代价，因为你可以看到 Claude 搜索 package.json，读取 Gemfile，尝试 npm test，被告知没有测试脚本，再试 yarn test，才发现实际使用的是 pnpm，直到这时才能开始你要求的工作。所有 Rails 项目或 Go 模块的答案都是相同的，每次都从零开始重新发现这些答案是浪费精力。

brief 是一个包含 54 种语言生态系统中 516 个工具的数据库，前面有一个单一的 Go 二进制文件，负责查找并在管道中输出 JSON，或在 TTY 上输出人类可读的摘要。数据集部分在其他地方并不存在：调用命令、配置文件位置，以及五百种工具在一个机器可读模式下的分类。CI 模板、devcontainer 生成器和编辑器入职流程是我找到的最接近的，每种都携带其中一部分数据，但没有共享的上游。我把 CLI 看作是该数据的单一视图，并期望还有其他视图。

指向一个目录、git URL 或注册表坐标（如 gem:rails 或 npm:express），它会报告二十个类别的工具链，每个类别都有运行命令和驱动它的配置文件，再加上它在常规位置找到的任何治理和社区文件（带有 SPDX 标识符的许可证、安全策略、CODEOWNERS、FUNDING.yml 等）。

brief .                       # local directory
brief gem:rails               # registry package, resolved to source repo
brief diff                    # only tools touched by changed files
brief missing                 # baseline categories with no tool configured
brief threat-model            # CWE/OWASP categories implied by the stack
brief sinks                   # dangerous functions in detected tools

检查全部 516 个定义可在 250 毫秒内完成，因为每次会话或流水线步骤开头运行的任何工具都不能让速度成为瓶颈；在其自己的博客仓库中，它能在约 220 毫秒内识别出 Jekyll、Bundler、Rake、Dependabot 和 GitHub Actions，而在 Go 项目中，输出如下：

$ brief .
Language:        Go
Package Manager: Go Modules (go mod download)
Test:            go test (go test ./...)
Lint:            golangci-lint (golangci-lint run)  [.golangci.yml]
Format:          gofmt (gofmt -w .)
Build:           GoReleaser (goreleaser release --clean)
Security:        govulncheck (govulncheck ./...)
CI:              GitHub Actions  [.github/workflows/]

我把它作为克隆任何内容后的第一件事来运行，并将其集成到我的全局代理指令中，这样每个 Claude 会话都会在执行任何其他操作之前先运行 brief。这通过一次工具调用来代理该仓库，节省了原本用于探索性 grep 和错误猜测的令牌。在功能分支上，brief diff 将报告范围缩小为仅由更改文件影响的工具，因此阅读它的人知道要运行 golangci-lint，因为 .go 文件发生了变化，而无需同时了解 monorepo 另一半中的 Python linter。

由于 JSON 输出遵循已发布的模式，它也可以作为其他工具的基础构件：brief --json . | jq -r '.tools.test[0].command.run' 可获取项目的多语言 CI 作业测试命令，而无需为每种语言编写特定情况；该查找可以驱动 devcontainer 或入职脚本；计划是在 ecosyste.ms 索引的每个仓库中运行它，以便为每个包提供栈元数据。

检测规则采用 TOML 而非 Go，这意味着添加工具只需在 knowledge/ 目录下新增一个文件，无需修改代码：包含名称、类别、标识其存在的文件或依赖项名称、运行命令，以及可选的 oss-taxonomy 标签（描述工具类型）。该分类体系是一个独立项目，用于定义“工具”的词汇；brief 则能识别项目使用了哪些工具。

依赖名称匹配由与 git-pkgs 相同的清单解析器驱动，因此工具定义可声明“若 bundle 中存在 rspec-core，则认为其存在”，而 brief 已原生支持读取 Gemfile、package.json、go.mod、Cargo.toml 及其他支持的锁文件格式，无需重复实现。

这些标签最初用于让 JSON 输出能明确“Web 框架”而非仅标注“构建工具”，但当数百个定义携带这些标签后，它们清晰地映射到 CWE 和 OWASP 分类体系。因此，对 Rails 项目进行威胁建模时，brief 无需扫描任何代码即可识别出 SQL 注入、批量赋值、XSS、CSRF 和 SSTI 等漏洞——因为这些正是 Rails 和 ActiveRecord 所暴露的风险点。此外，每个工具定义还包含约 700 个具体危险函数，可作为你从未接触过的技术栈安全审查中合理的 grep 起始列表。

$ brief sinks .
ActiveRecord:
  Arel.sql            sql_injection      CWE-89
  find_by_sql         sql_injection      CWE-89
  where               sql_injection      CWE-89   string interpolation only
Rails:
  html_safe           xss                CWE-79
  redirect_to         open_redirect      CWE-601  when target is from params
  render inline:      ssti               CWE-1336
Ruby:
  eval                code_injection     CWE-95
  Marshal.load        deserialization    CWE-502

brief 的缺失检测会反转检查逻辑，报告五个基线类别（测试、lint、格式化、类型检查、文档）中哪些在检测到的生态系统中未配置对应工具，并为每个缺口推荐标准选择。同时，检测引擎也可作为 Go 库直接导入使用，避免调用 shell。

工具定义位于 knowledge/ 目录，我尤其欢迎为此目录提交新定义的 PR，特别是针对我不常使用的生态系统。若你将 brief 指向某个项目并发现误判，请提 issue 或在 Mastodon 上联系我。

brew install git-pkgs/git-pkgs/brief / github.com/git-pkgs/brief