forge

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Forge

Delegate complex, multi-step development work to an autonomous agent that builds and verifies code.

将复杂的多步骤开发工作委托给可构建并验证代码的自主Agent。

When to Use Forge

何时使用Forge

Use forge when:

The task targets a different repo (
```
-C ~/other-project
```
)
The work is complex enough to benefit from autonomous agent execution with verification
You have spec files describing outcomes to implement
You want to run multiple specs in parallel

Don't use forge when:

The task is a simple edit you can make directly
The user is asking a question, not requesting implementation
The work is in the current file / current repo and straightforward

使用Forge的场景：

任务针对其他仓库（
```
-C ~/other-project
```
）
工作足够复杂，可通过带验证的自主Agent执行获益
你拥有描述待实现结果的spec文件
你需要并行运行多个spec

不应使用Forge的场景：

任务是可直接完成的简单编辑操作
用户只是提出问题，而非要求实现功能
工作内容位于当前文件/当前仓库，且简单直接

Commands

命令

forge run

bash

forge run "add auth middleware"                          # Simple task
forge run --spec specs/auth.md "implement this"          # With spec file
forge run --spec-dir ./specs/ -P "implement all"         # Parallel specs
forge run -C ~/other-repo "fix the login bug"            # Target different repo
forge run --rerun-failed -P "fix failures"               # Rerun failed specs
forge run --resume <session-id> "continue"               # Resume interrupted session
forge "quick task"                                       # Shorthand (no 'run')

Important flags:

```
-s, --spec <path>
```
-- Spec file. Prompt becomes additional context.
```
-S, --spec-dir <path>
```
-- Directory of specs. Each
```
.md
```
runs separately.
```
-P, --parallel
```
-- Run specs concurrently (auto-tuned concurrency).
```
--sequential-first <n>
```
-- Run first N specs sequentially, then parallelize.
```
-C, --cwd <path>
```
-- Target repo directory.
```
-w, --watch
```
-- Auto-split tmux pane with live logs.
```
--dry-run
```
-- Preview tasks and estimate cost without executing.

Run

forge run --help

for all flags.

bash

forge run "add auth middleware"                          # Simple task
forge run --spec specs/auth.md "implement this"          # With spec file
forge run --spec-dir ./specs/ -P "implement all"         # Parallel specs
forge run -C ~/other-repo "fix the login bug"            # Target different repo
forge run --rerun-failed -P "fix failures"               # Rerun failed specs
forge run --resume <session-id> "continue"               # Resume interrupted session
forge "quick task"                                       # Shorthand (no 'run')

重要参数：

```
-s, --spec <path>
```
-- Spec文件，提示信息将作为额外上下文。
```
-S, --spec-dir <path>
```
-- Spec文件目录，每个
```
.md
```
文件将单独运行。
```
-P, --parallel
```
-- 并行运行spec（自动调优并发数）。
```
--sequential-first <n>
```
-- 先顺序运行前N个spec，再并行运行剩余部分。
```
-C, --cwd <path>
```
-- 目标仓库目录。
```
-w, --watch
```
-- 自动拆分tmux面板以显示实时日志。
```
--dry-run
```
-- 预览任务并估算成本，不实际执行。

运行

forge run --help

查看所有参数。

forge audit

Reviews codebase against specs. Produces new spec files for remaining work — feed them back into

forge run --spec-dir

bash

forge audit specs/                              # Audit, output to specs/audit/
forge audit specs/ -o ./remediation/            # Custom output dir
forge audit specs/ -C ~/target-repo             # Different repo

对照spec审查代码库，为未完成的工作生成新的spec文件，可将其传入

forge run --spec-dir

继续执行。

bash

forge audit specs/                              # Audit, output to specs/audit/
forge audit specs/ -o ./remediation/            # Custom output dir
forge audit specs/ -C ~/target-repo             # Different repo

forge review

Reviews recent git changes for bugs and quality issues.

bash

forge review                                    # Review main...HEAD
forge review HEAD~5...HEAD                      # Specific range
forge review --dry-run -o findings.md           # Report only, write to file

审查近期的Git变更，查找Bug和质量问题。

bash

forge review                                    # Review main...HEAD
forge review HEAD~5...HEAD                      # Specific range
forge review --dry-run -o findings.md           # Report only, write to file

forge watch

Live-tail session logs with colored output. Auto-exits when session completes.

bash

forge watch                                     # Watch latest session
forge watch <session-id>                        # Watch specific session

实时跟踪会话日志并显示彩色输出，会话完成后自动退出。

bash

forge watch                                     # Watch latest session
forge watch <session-id>                        # Watch specific session

forge status

bash

forge status                                    # Latest run
forge status --all                              # All runs
forge status -n 5                               # Last 5 runs

bash

forge status                                    # Latest run
forge status --all                              # All runs
forge status -n 5                               # Last 5 runs

Recipes

使用方案

Spec-driven development

基于Spec的开发

bash

undefined

bash

undefined

1. Write specs as .md files (see references/writing-specs.md)

2. Run them in parallel

forge run --spec-dir ./specs/ -P "implement all specs"

3. Rerun any failures

forge run --rerun-failed -P "fix failures"

4. Check results

forge status

undefined

forge status

undefined

Foundation specs first, then parallelize

先执行基础Spec，再并行运行

Number-prefix specs for ordering. Foundations run sequentially before the parallel phase:

bash

forge run --spec-dir ./specs/ -P --sequential-first 2 "implement"

为Spec文件添加数字前缀以指定顺序，基础Spec将在并行阶段前顺序执行：

bash

forge run --spec-dir ./specs/ -P --sequential-first 2 "implement"

Runs 01-.md, 02-.md sequentially, then 03+ in parallel

undefined

undefined

Audit-then-fix loop

审计-修复循环

bash

forge audit specs/ -C ~/project                 # Find gaps
forge run --spec-dir specs/audit/ -P -C ~/project "fix remaining"

bash

forge audit specs/ -C ~/project                 # Find gaps
forge run --spec-dir specs/audit/ -P -C ~/project "fix remaining"

Resume or fork after interruption

中断后恢复或分支

bash

forge run --resume <session-id> "continue"               # Pick up where you left off
forge run --fork <session-id> "try different approach"    # Branch from that point

bash

forge run --resume <session-id> "continue"               # Pick up where you left off
forge run --fork <session-id> "try different approach"    # Branch from that point

Deep-Dive References

深度参考

Reference	Load when
writing-specs.md	Writing spec files for forge to execute
parallel-execution.md	Tuning concurrency, understanding cost, monitoring parallel runs

参考文档	适用场景
writing-specs.md	编写供Forge执行的spec文件时
parallel-execution.md	调优并发数、了解成本、监控并行运行时