Getting started

What it is

Requirements live in Reqfile.yaml files next to the code. Each one says what must hold, why, for whom, and how it is checked: with an existing tool when the rule is mechanical (a command check), or with Jev, a decision model returning calibrated probabilities, when it needs judgment (a decision check). A requirement written once can be taken by reference in other folders and repositories (use).

$ reqfile check
FAIL_FAST  services/api/handler.py:42  Do not use bare `except` (E722)
  fix: Catch the specific expected error and handle it visibly, or let it propagate.
advisory  DECOMPLECT  services/sync/worker.ts:88  p=0.91  It mixes several jobs.
  fix: Split the I/O from the logic into two functions.

14 checks run, 2 with nothing to check, 212 code units judged. 1 violation, 1 advisory finding, 0 errors.

Set up with an agent

Give your coding agent (Claude Code, Codex, Cursor…) this prompt. It is a request to the agent, not a shell command:

set up https://reqfile.dev/SKILL.md

The agent skill tells it to:

1. inspect the repository's agent instructions, existing Reqfiles, tool versions, package scripts and CI, and preserve them;
2. install the CLI through the project's tool manager, respecting an existing version pin;
3. if there are no requirements, derive a small initial set from your stated constraints and the checks the project already runs, each with a precise must, its why, a working check and an actionable fix_hint;
4. run reqfile list, reqfile explain . and reqfile check, and report the actual coverage and remaining findings;
5. add the everyday workflow to the repository's agent instructions, and a CI job.

Install

With mise, from the prebuilt binaries (macOS and Linux):

# mise.toml
[tools]
"github:arkadia-so/reqfile" = "0.6.0"

Or with the install script:

curl -LsSf https://github.com/arkadia-so/reqfile/releases/download/v0.6.0/reqfile-installer.sh | sh

Or build the release from source with Rust 1.90 or later:

cargo install --git https://github.com/arkadia-so/reqfile --tag v0.6.0 --locked

reqfile runs on macOS and Linux; Windows is not supported. It needs git, sh, tar (for requirements taken from other repositories), and the tools your Reqfiles' commands call.

Write a first Reqfile

At the repository root, for a Python project already using Ruff:

reqfile: 1
code:
  - id: EXPLICIT_EXCEPTIONS
    must: Exception handlers name the exceptions they catch; no bare except clauses.
    why: A bare except also catches interrupts and hides unexpected failures.
    checks:
      - command:
          run: ruff check --isolated --select E722 --output-format sarif
          files: "**/*.py"
          pass_files: true
          format: sarif
          fast: true
          fix_hint: Catch the specific expected exception or let it propagate.

Start from the checks the project already runs: its linters, its tests, its scripts. Add a decision check only when a rule needs judgment. You can also take requirements someone published with reqfile add.

Run it

reqfile list                     # every requirement, with its type and checks
reqfile explain src/             # the requirements that apply to a folder
reqfile check                    # run every check
reqfile check --fast --changed   # the short loop, while editing

Fix a finding using its requirement, location and fix hint, then rerun. Exit 0 means every blocking check ran and passed; 1 means blocking violations; 3 means a check could not run or a configuration is wrong, which is never a pass. See exit codes.

A repository without any Reqfile.yaml is an error, not a green run: reqfile check and reqfile eval exit 3 and say how to set reqfile up.

$ reqfile check
error  no Reqfile.yaml in this repository: none among the files git lists under /work/app (tracked, or untracked and not ignored), so there is nothing to check.

    reqfile checks a codebase against requirements written in Reqfile.yaml files. […]

    To set it up:
      - If you are an agent: read https://reqfile.dev/SKILL.md and follow "When asked to set up Reqfile".
      - To take requirements someone published: reqfile add <owner/repo@tag>
      - Or write Reqfile.yaml at the repository root, for example: […]

In your agent instructions

Add this to AGENTS.md, CLAUDE.md or whichever instructions file your agents read:

Before editing a folder, run `reqfile explain <folder>`.
Before finishing, run `reqfile check --fast --changed` and fix blocking findings.
Run the full `reqfile check` before declaring the requirements checks complete.
Reqfile usage and setup: https://reqfile.dev/SKILL.md

As a Claude Code hook

A Stop hook sends violations back to the agent before it finishes:

{
  "hooks": {
    "Stop": [
      { "hooks": [{ "type": "command",
        "command": "jq -e '.stop_hook_active' >/dev/null && exit 0; reqfile check --fast --changed >&2 || exit 2" }] }
    ]
  }
}

With --fast, only decision checks (advisory unless blocking) and the command checks declared fast: true run, so the hook blocks only on those; declare quick commands fast. The stop_hook_active guard lets the agent stop after one forced retry, which avoids infinite loops but allows finishing with violations left: CI remains the gate. When the output holds decide lines, tell the agent not to fix the findings marked breaks: but to ask you: they contradict another requirement.

In CI

As a required check on pull requests:

# .github/workflows/reqfile.yml
name: reqfile
on: pull_request
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - run: cargo install --git https://github.com/arkadia-so/reqfile --tag v0.6.0 --locked
      # Also install the tools the Reqfiles' commands use (ruff, ast-grep, knip, ...).
      - run: reqfile check
        env:
          OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
      - run: reqfile eval

fetch-depth: 0 gives --changed the history it compares against. Decision answers are cached in .git/reqfile/; keep that folder between runs (for example with actions/cache) to avoid asking again about unchanged code.

Security

Reqfiles, configs and requirements taken with use are executable code:

• A command check runs its shell command on your machine or CI runner, with your environment.
• A config chooses the Jev endpoint and the environment variable whose value is sent to it as the API key.
• Decision checks send the code they select to the configured provider.
• Taking a requirement from another repository means running that repository's commands in your CI. Pin it to a commit you trust, and read what reqfile add prints before adding it.