# Best Practices

Getting the most out of Forge is less about configuration and more about leaning
into the workflow. These practices help Forge do what it does best: keep your
specs, code, and team in sync while protecting you from runaway loops and stale
truth.

## Let adaptive depth pick the ceremony

Adaptive depth triages each change and chooses how much of the spine it needs.
**Trust it — don't force a mode.** A trivial docs fix fast-forwards; a payments
change takes the full spine. Forcing every change to the same depth either adds
friction to small work or under-scrutinizes risky work.

::: tip You can always go deeper
Adaptive depth only chooses a starting point. When a change deserves more
scrutiny than the triage suggested, force a deeper path. See
[adaptive depth](/guide/workflow#adaptive-depth).
:::

## Keep the constitution current

The constitution is standing project truth, and it is load-bearing:
**constitution conflicts cap the `analyze` quality score.** A stale constitution
quietly drags down every quality assessment. Revisit it whenever your principles
or constraints change, so the score reflects reality rather than drift against an
outdated document.

## Commit `.forge/` so the team shares specs

Everything under `.forge/` is plain files. **Commit it** so your whole team
shares the same specs, changes, and memory. When `.forge/` is versioned with the
code, specs travel with the repository, in-flight changes can be resumed by
anyone, and project memory compounds across the team.

::: warning Keep local config local
`.forge/config.local.yaml` is gitignored on purpose — it is per-machine. Keep
machine-specific settings there and shared settings in `.forge/config.yaml`. See
[Configuration](/guide/configuration).
:::

## Run the dashboard while you work

Keep the generated dashboard open as you work:

```sh
forge docs serve
```

It gives you a live view of specs, changes, task status, budget, and timeline —
so you always know where a change stands. See the
[dashboard overview](/features/dashboard).

## Connect the harness to your agent via hooks

Wire the harness into your agent with hooks so the runtime guardrails
auto-populate from live activity. Once connected, the circuit-breaker, budget
ledger, and attributed timeline fill in automatically as your agent works —
no manual recording. See [live agent hooks](/harness/live-agent-hooks).

## Use the circuit-breaker to stop runaway loops

Verification runs under a **circuit-breaker** that halts runaway
verify/implement loops before they burn time and budget. Let it do its job, and
tune it when a change legitimately needs more attempts. See
[circuit-breaker](/harness/circuit-breaker).

## Run analyze and drift periodically

Make `analyze` and `drift` part of your rhythm, not just a final gate:

- `analyze` gives a 100-point quality score for the current state.
- `drift` surfaces **Ghost** (code with no spec), **Phantom** (spec with no
  code), and **Mutated** (code and spec disagree) divergence.

Catching drift early keeps `specs/` trustworthy. See
[cross-cutting commands](/guide/workflow#cross-cutting-commands).

## Archive completed changes

Archive changes as soon as they pass verify. Archiving promotes the change's
delta specs into canonical `specs/` and freezes the change in the immutable
audit trail. Leaving finished work un-archived lets `specs/` fall behind what the
code actually does.

::: tip Archive means done
`archive` is blocked while any task is blocked or not done, so a green archive is
a real signal. See [honest task status](/guide/workflow#honest-task-status).
:::

## Migrate existing projects with `forge import`

Adopting Forge on an existing codebase? **Migrate with `forge import` instead of
rewriting.** Import brings your project into Forge's model losslessly — anything
that does not map cleanly lands in `_imported/` rather than being lost — so you
adopt the workflow without throwing away existing structure. See
[migration](/features/migration).

## Summary

| Practice | Why it matters |
| --- | --- |
| Let adaptive depth choose | Right ceremony per change |
| Keep the constitution current | Stale constitution caps `analyze` score |
| Commit `.forge/` | Team shares specs, changes, memory |
| Run `forge docs serve` | Live visibility while you work |
| Connect harness hooks | Breaker/budget/timeline auto-populate |
| Use the circuit-breaker | Stops runaway loops |
| Run analyze/drift periodically | Catch drift early |
| Archive completed changes | Keeps `specs/` canonical |
| Import, don't rewrite | Lossless migration |

## Next steps

- [The Workflow](/guide/workflow) — the spine these practices support.
- [Configuration](/guide/configuration) — settings referenced above.
- [Circuit-breaker](/harness/circuit-breaker) — bound your verify loops.
- [Migration](/features/migration) — adopt Forge on existing projects.