rice-rail：让代码库拥有自主工程准则的终端优先工具包

rice-rail 是一个终端优先、与 Agent 无关的项目收敛工具包。它通过分析代码库、生成工程准则宪章、构建项目专属工具链，实现「人类定义目标，工具强制执行，LLM 只处理工具无法完成的任务」的确定性工作流。

随着 Claude Code、GitHub Copilot、Gemini 等 AI 编程助手普及，开发者面临一个新问题：如何让这些工具真正理解并遵循项目的工程标准？不同项目有不同的架构风格、代码规范和质量要求，而通用 AI 助手往往缺乏项目特定的上下文，导致建议不一致或需要反复纠正。

rice-rail 正是为解决这一问题而生。这个开源项目提出了一种全新的思路：让代码库本身拥有「工程宪章」，AI 助手只是消费这些宪章的执行者。这种「仓库拥有准则，Agent 消费准则」的架构，为 AI 辅助开发提供了可扩展、可迁移的解决方案。

rice-rail 是一个终端优先、与 Agent 无关的项目收敛工具包（Project Convergence Toolkit）。它的核心工作流程可以概括为：进入任意软件仓库，分析其技术栈和结构，通过自适应问答了解团队的工程标准，发现现有工具链的缺口，最终生成一套项目专属的工具包，并运行确定性的「意图→工具→验证→优化」循环。

项目的核心理念体现在几个关键原则上：

仓库拥有准则（Repo owns doctrine）：工程准则以版本控制的 YAML 文件形式存在（constitution.yaml），而非分散在提示词或文档中。这使得准则可以随代码一起演进、审查和回滚。

Agent 无关性（Agent-agnostic）：Claude Code、Codex、Gemini、Copilot、Qwen、OpenCode、Ollama、Aider 等主流 AI 工具都有对应的适配器，开发者可以自由切换或同时使用多个工具。

工具优先于 LLM（Tools before LLMs）：确定性转换（如格式化、自动修复、规范化）由专用工具先执行，LLM 只处理工具无法完成的语义层面问题。这种分工既保证了结果的一致性，又控制了成本。

默认安全（Safe by default）：不安全的重写操作需要显式标志，基线工作和特性开发被明确分离，避免意外破坏。

rice-rail init 命令是整个过程的起点。它会扫描目标仓库，识别编程语言、包管理器、构建系统、CI 配置、工具配置和架构线索，然后通过自适应问答收集团队的工程标准。最终产出包括：

• constitution.yaml：项目的工程宪章，定义架构风格、质量标准、安全策略和自动化偏好
• profile.yaml：推断的仓库画像，包含置信度评分
• tool-inventory.yaml：在仓库和 PATH 中发现的工具清单
• gap-report.yaml：现有能力与需求之间的差距分析
• rollout-plan.yaml：填补差距的有序步骤
• interview-log.md：完整的问答记录，用于审计和复现

rice-rail build-toolkit 命令基于宪章生成项目专属的工具链，包括：

• 包装脚本（如 bin/rice-rail-check、bin/rice-rail-fix）
• 规则目录（Semgrep、ast-grep、自定义规则）
• 代码重构模板（Codemod）
• CLI Agent 的工作流包
• Agent 原生技能（Claude Code、Gemini、Copilot、Qwen、OpenCode 等）
• CI 工作流（GitHub Actions）
• 操作指南、规则目录和工具包概览文档
• 溯源追踪（Provenance tracking）

rice-rail cycle "<意图>" 是日常工作的核心命令。它执行完整的「意图→工具→验证→优化」循环：

1. 意图解析：将自然语言描述转换为结构化的任务定义
2. 工具执行：优先运行确定性转换（格式化、lint 修复、规范化）
3. 验证检查：运行所有阻塞性检查（lint、测试、类型检查、架构检查）
4. 优化迭代：仅将残余的语义问题暴露给 Agent

这种设计确保工具处理机械性工作，Agent 只处理需要判断力的模糊问题，实现了效率与智能的最佳平衡。

rice-rail 的 constitution.yaml 采用强类型模式，核心结构包括：

version: 1
project:
  name: my-service
  repo_type: single
  languages: [go, typescript]

architecture:
  target_style: hexagonal
  layering:
    enabled: true
    forbidden_dependencies:
      - from: domain
        to: infrastructure

quality:
  safety_mode: strict
  block_on: [lint, tests, typecheck, architecture]
  max_changed_files_per_cycle: 10

automation:
  allow_safe_autofix: true
  allow_unsafe_autofix: false

这种声明式配置使得工程标准可以被版本控制、代码审查和自动化验证。当团队成员对某个规则有疑问时，rice-rail explain <rule-id> 可以追溯该规则的起源——是谁推断的、谁确认的、由什么生成的。

rice-rail 内置了对主流技术栈的深度支持：

语言	Lint	格式化	类型检查	测试	架构检查
Go	golangci-lint	gofmt	go vet	go test	—
TypeScript/JS	ESLint, Biome	Prettier, Biome	tsc	Jest, Vitest	dependency-cruiser
Python	Ruff	Ruff	Pyright, mypy	pytest	—
Rust	Clippy	rustfmt	—	cargo test	—

此外，通过 constitution.yaml 的 tool_preferences.custom 配置，任何 CLI 工具都可以被集成，支持文本、JSON 和 SARIF 输出格式解析。