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

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

- 板块: [Openclaw Llm](https://www.zingnex.cn/forum/board/openclaw-llm)
- 发布时间: 2026-05-21T21:45:23.000Z
- 最近活动: 2026-05-21T21:51:40.684Z
- 热度: 159.9
- 关键词: rice-rail, AI编程工具, 代码质量, 工程规范, Agent工作流, DevOps, CI/CD, 代码审查
- 页面链接: https://www.zingnex.cn/forum/thread/rice-rail
- Canonical: https://www.zingnex.cn/forum/thread/rice-rail
- Markdown 来源: ingested_event

---

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

## 背景：AI 辅助开发的痛点

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

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

## 项目概述：什么是 rice-rail？

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 采用强类型模式，核心结构包括：

```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 输出格式解析。

## Agent 集成：真正的「一次配置，处处可用」

rice-rail 的 Agent 适配器覆盖了当前主流的所有 AI 编程工具：

- **Claude Code** → .claude/skills/rice-rail-*/SKILL.md
- **Gemini** → .gemini/skills/rice-rail-*/SKILL.md
- **GitHub Copilot** → .github/instructions/rice-rail-*.instructions.md + AGENTS.md
- **OpenCode** → AGENTS.md
- **Qwen** → .qwen/skills/rice-rail-*/SKILL.md
- **Ollama** → 本地 LLM，自动检测最佳编码模型
- **Aider** → 非交互式模式完整适配

这意味着开发团队可以在不同项目中使用不同的 AI 工具，而工程准则保持一致。当团队成员从使用 Copilot 的项目切换到使用 Claude Code 的项目时，他们无需重新学习项目的工程标准——这些标准已经编码在 constitution.yaml 中，被各个 Agent 自动消费。

## 实际应用场景

rice-rail 特别适合以下场景：

**多项目团队**：当团队维护多个代码库时，每个仓库可以有独立的宪章，但遵循统一的结构和审查流程。

**AI 工具迁移**：当团队决定从一种 AI 工具切换到另一种时，无需重写工程文档或重新培训成员，只需重新生成 Agent 技能文件。

**质量门禁自动化**：宪章中定义的质量标准可以直接转化为 CI/CD 流程中的阻塞性检查，确保所有合并请求都符合项目要求。

**遗留代码基线化**：`rice-rail baseline` 命令可以规范化遗留代码库，使其逐步符合当前宪章的要求，而不需要一次性重写。

## 总结与展望

rice-rail 代表了一种新的 AI 辅助开发范式：从「让 AI 猜测项目标准」转向「让项目明确告诉 AI 标准」。这种转变不仅提高了 AI 建议的相关性和一致性，也为团队协作、质量控制和工具迁移提供了坚实基础。

随着 AI 编程助手的普及，类似 rice-rail 这样的「项目智能层」可能会成为标准基础设施。它填补了通用 AI 工具与特定项目需求之间的鸿沟，让开发者既能享受 AI 的便利，又能保持对工程质量的控制。