> ## Documentation Index
> Fetch the complete documentation index at: https://gump.top/sdlc-harness-docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Best practices

> Help developers and coding Agents use SDLC Harness more reliably.

## Planning and selection

* Keep each feature small enough to implement and verify independently in one Agent session; split it first if it is too large.
* Write `behavior` as observable outcomes, not internal implementation steps.
* Use lower `priority` values for higher-priority work, together with `claim --next` to select ready work automatically.
* Run `status` at the start of every session instead of guessing the current state from the previous conversation.
* Write an ADR before making high-risk, cross-boundary, or difficult-to-reverse changes.
* Once every feature in a milestone is `passing`, run `milestone archive` before planning the next one, so `feature_list.json` stays focused on current work instead of accumulating every completed milestone.

## Verification and evidence

* Use deterministic, repeatable commands with reliable exit codes for verification.
* Link each verification item only to the acceptance criteria it actually demonstrates.
* Use `verify` for automated checks; declare keyboard experience, visual confirmation, and similar human judgments as manual, then record them with `evidence manual`.
* Verify again after code changes; record the latest review after the latest verification.
* If an approved artifact changes in any way, record a new approval.

## Collaboration

* In Solo mode, you normally do not need to call the low-level `claim` command, but `feature start` still establishes the lifecycle claim required for the work.
* `owner` identifies responsibility, while `actor` distinguishes different Agent sessions for the same `owner`.
* For long-running work, use `claim renew` before the lease expires so active work is not mistaken as available for takeover.
* Give parallel Agents separate workspaces, with one feature per workspace.
* Keep the reviewer separate from the claim `owner` so implementers do not review their own completion.

## Sessions and Git

* Run `session close` at the end of a session, and include failed checks, uncommitted files, and next steps in the handoff.
* Commit `feature_list.json`, audit events, and protocol documents; do not commit local snapshots or `.worktrees/`.
* Use `--push` for cross-machine claims. A regular local claim does not provide a real-time distributed lock.
* Before `workspace remove` or `workspace prune`, confirm that work is committed and pushed; do not treat `--force` as a routine cleanup option.

## Fields you should not edit directly

The CLI should maintain claims, workspaces, test/review evidence, and lifecycle states. Manual edits can bypass `owner`, commit, chronology, WIP, and concurrent-write checks, leaving state that appears valid but cannot be reproduced with confidence.

<Tip>
  You can give an Agent a standard completion requirement: show the results of `verify`, `review record`, `feature complete`, `validate`, and `session close`, and identify anything that remains incomplete.
</Tip>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.