7. Instructions for agents
A coding agent (Claude Code, Codex, Copilot...) reads an AGENTS.md (or CLAUDE.md) to learn how to build and check a project. Written by hand, it goes stale with the first new mode. fobis agents-md writes it from the facts: the fobos modes with their flags, the commands, the tests, the code's kinds and parallelism.
console
$ fobis agents-md --print
<!-- fobis:begin agents-md -->
<!-- Generated by `fobis agents-md` from the fobos and the sources: regenerate it, do not edit it. Text outside the fobis:begin/end markers is yours and is kept. -->
## Building and checking quad
The build tool is FoBiS (`fobis`): it resolves the module dependencies itself, so there is no makefile to edit. Build settings live in the `fobos` file, one section per mode. Every command below accepts `--json`; with it, stdout holds only the JSON document.
### Modes
| Mode | Compiler | Builds | Flags | Parallel | Defines |
|---|---|---|---|---|---|
| `debug` | gnu | program `integrate` from `src/integrate.F90` | -O0, debug info, runtime checks | - | - |
| `release` | gnu | program `integrate` from `src/integrate.F90` | -O3 | - | - |
| `static` | gnu | static library `libquad.a` from `src/quad_rules.F90` | -O2 | - | - |
| `shared` | gnu | shared library `libquad.so` from `src/quad_rules.F90` | -O2 | - | - |
| `coverage` | gnu | program `integrate` from `src/integrate.F90` | -O0, debug info | - | - |
| `openmp` | gnu | program `sweep` from `src/sweep.F90` | -O3 | OpenMP | - |
| `mpi` | gnu | program `integrate_mpi` from `src/integrate_mpi.F90` | -O3 | MPI | - |
| `python` | gnu | shared library `libquad_c.so` from `bindings/quad_c.f90` | -O2 | - | - |
Without `--mode` FoBiS uses the first mode, `debug`. `fobis introspect --mode MODE --buildoptions` prints a mode's exact flags.
### Commands
- Dependencies: `fobis fetch` (into `.fobis_deps`) before the first build.
- Build: `fobis build --mode debug`; on failure `fobis build --json` lists the located diagnoses.
- Tests (3 programs in `test/`): `fobis test`; one test: `fobis test --filter NAME`.
- Doctests (in the comments of 1 file): `fobis doctests`.
- Runtime checks on any mode: add `--shadow checks` to build, run or test.
- Lint: `fobis lint`; only the lines you changed: `fobis review`.
- Questions about the code, instead of grep: `fobis query callers NAME` (also `callees`, `uses MODULE`, `writers VAR`, `readers VAR`, `defines NAME`, `interface NAME`, `region FILE:LINE`, `device VAR`, `mpi`).
- `fobis rule --ex dist`: A source archive
- `fobis rule --ex errors`: The table of errors, from the release build
- `fobis rule --ex smoke`: The last line of the program's output
### Verifying a change
No case is declared, so tests are the only check of results. Cases declared in the fobos (`[case:NAME]`, see `fobis case --help`) let `fobis verify` and `fobis diff-run` compare results.
### Code facts
- Sources (mode `debug`): `src`, `test`; 11 files (10 `.F90`, 1 `.f`), 4 modules.
- Programs: `src/integrate.F90 (integrate)`, `src/integrate_mpi.F90 (integrate_mpi)`, `src/sweep.F90 (sweep)`, `test/test_exactness.F90 (test_exactness)`, `test/test_order.F90 (test_order)`, `test/test_romberg.F90 (test_romberg)`.
- Dependencies (fobos `[dependencies]`): penf (https://github.com/szaghi/PENF :: tag=v2.0.1). Change them upstream, not here.
- `real` declarations by kind: `R8P` 39 (15 digits, from `quad_rules`), `DOUBLE PRECISION` 7.
- `integer` declarations by kind: `default` 21.
- Units without `implicit none`: `src/romberg.f: function romb`.
- Parallelism: OpenMP directives in 1 file; MPI through `mpi` in 1 file (5 MPI calls: `fobis query mpi`).
### MCP
The same facts and checks are MCP tools: `claude mcp add fobis -- fobis mcp` (any MCP client: command `fobis mcp` over stdio).
<!-- fobis:end agents-md -->fobis agents-md writes the block into AGENTS.md (-o CLAUDE.md for another file), between the markers: text around them is yours and is kept. fobis agents-md --check exits 1 when the block is stale, for CI. The content is deterministic: no dates, no machine state.
What you learned
fobis agents-md, --print, -o, --check. Reference: instructions for agents.
This is the end of the fourth track. The fifth asks the question the linter cannot answer: are the results right?