很多人一开始会把 Claude Code 当成一个交互式命令行工具：打开终端，输入需求，让它读代码、改文件、跑测试。但如果只停留在交互式使用，其实浪费了它最适合自动化的一部分能力。

claude -p 提供了非交互模式，可以让 Claude Code 接收一段 prompt，完成任务后把结果输出到 stdout，然后退出。这意味着它可以被 Rails、Sidekiq、Solid Queue、cron、systemd timer 或任何本地调度系统调用，变成一个“本地 agent runner”。

为什么不是直接用 API？

API 适合稳定的业务调用，比如客服、内容生成、结构化分析、线上服务推理。

但 claude -p 更适合本地开发自动化：

• 读取项目文件
• 搜索代码
• 修改代码
• 执行测试
• 生成报告
• 检查日志
• 完成 repo 内的维护任务

也就是说，API 更像“模型服务”，而 claude -p 更像“带工具能力的本地工程 agent”。

Rails 怎么接入？

最简单的方式是把 agent 任务抽象成一张表。

例如：

create_table :agent_tasks do |t|
  t.text :instruction, null: false
  t.string :status, null: false, default: "pending"
  t.text :output
  t.text :error
  t.integer :exit_code
  t.datetime :started_at
  t.datetime :finished_at

  t.timestamps
end

然后用后台任务执行：

class AgentTaskJob < ApplicationJob
  queue_as :default

  def perform(task_id)
    task = AgentTask.find(task_id)

    task.update!(status: "running", started_at: Time.current)

    prompt = <<~PROMPT
      你是这个 Rails 项目的本地开发 agent。

      任务：
      #{task.instruction}

      要求：
      - 先理解现有代码
      - 只修改必要文件
      - 修改后运行相关测试
      - 最后输出 JSON，包含 status、summary、files_changed、tests_run
    PROMPT

    stdout, stderr, status = Open3.capture3(
      "claude",
      "-p",
      prompt,
      "--output-format", "json",
      "--max-turns", "8",
      "--max-budget-usd", "3",
      "--permission-mode", "acceptEdits",
      chdir: Rails.root.to_s
    )

    task.update!(
      status: status.success? ? "completed" : "failed",
      output: stdout,
      error: stderr,
      exit_code: status.exitstatus,
      finished_at: Time.current
    )
  rescue => e
    task.update!(
      status: "failed",
      error: "#{e.class}: #{e.message}",
      finished_at: Time.current
    )
  end
end

这样 Rails 就不需要自己实现 agent loop，也不需要自己封装文件读写、shell 执行、代码搜索等能力。它只负责调度、记录状态、限制权限和展示结果。

推荐的任务类型

适合自动执行的任务包括：

• 每天检查 flaky tests
• 定时扫描 TODO / FIXME
• 自动分析错误日志
• 生成代码审查报告
• 检查依赖升级风险
• 为某个 issue 草拟修复方案
• 对最近提交生成 changelog
• 在隔离 worktree 中尝试修 bug

不太适合直接自动执行的任务包括：

• 数据库破坏性迁移
• 自动部署生产环境
• 大规模重构后直接 merge
• 执行不可逆 shell 命令
• 没有测试覆盖的核心业务改动

这些任务可以让 agent 生成方案或 PR，但不应该让它无审批直接落地。

权限边界很重要

最危险的做法是直接把调度系统和：

claude -p --dangerously-skip-permissions

绑在一起。

这样虽然“自动化程度高”，但风险也高。更稳妥的方式是分级授权：

• 只读任务：允许 Read、Grep、Glob
• 分析任务：允许 Bash 跑安全命令，例如测试、lint、git diff
• 修改任务：允许 Edit，但在独立 branch 或 worktree 里执行
• 高风险任务：只生成 patch 或报告，不自动应用

对于 Rails 应用，最好再加一层业务上的白名单。例如只有管理员创建的任务可以触发代码修改，普通定时任务只能生成报告。

接近 API 的效果，但不是 API

通过 claude -p --output-format json，Rails 可以拿到结构化输出，并把结果写回数据库。从使用效果上看，它很像调用 API：

1. Rails 创建任务
2. 后台 worker 执行 agent
3. agent 返回 JSON
4. Rails 展示状态和结果

但本质上它仍然是本地 CLI 调用。它依赖本机环境、Claude Code 登录状态、项目目录、权限配置和 shell 环境。

如果你要做生产级、多用户、稳定 SLA 的 agent 服务，更推荐 Claude Agent SDK 或 Claude API。如果你要做的是“让我的本地 Rails 应用调度 agent 自动干活”，claude -p 是一个非常直接、工程成本很低的方案。

最佳实践

实际落地时，建议遵守几个规则：

• 每个任务设置超时
• 每个任务设置预算上限
• 每次执行记录 stdout、stderr、exit code
• 修改代码时使用独立 branch 或 worktree
• agent 输出尽量要求 JSON
• 高风险任务必须人工确认
• 定时任务避免并发修改同一个 repo
• 把 prompt 模板版本化，方便回溯

总结

claude -p 可以和本地 Rails 调度系统很好地结合起来。

Rails 负责调度、权限、记录和展示；Claude Code 负责理解代码、使用工具、执行任务和生成结果。这个组合特别适合个人开发环境、内部工具、自动维护脚本和工程效率系统。

它不是 Claude API 的替代品，但在“本地 agent 自动做事”这个场景里，它反而更贴近真实需求。