+++
name = "_overview"
+++
# qualifier — guide for AI coding agents
You are an AI coding agent in a user's repository. The `qualifier` CLI is
installed. This page tells you what qualifier is, when to use it, and how to
get more detail on any specific feature.
## What it is
Qualifier records *annotations* — structured, content-addressed notes about
software artifacts (files, directories, line ranges). Annotations live in
`.qual` files alongside the code, are intended to be committed to version
control, and form a durable, reviewable record of quality observations
attached to specific places in the codebase.
## When to use it
- You found a bug, smell, risk, or stylistic concern that survives this
edit and is worth surfacing for whoever touches the code next. Record it.
## When NOT to use it
- One-off scratch debugging notes. Use scratch space.
- Information that belongs in the commit message (what *this* change does
and why). Use git.
- Project-wide policy or architecture decisions. Those belong in
`docs/` or an ADR, not as an annotation on a file.
## Quickstart
```bash
# Record a concern about a function in src/foo.rs
qualifier record concern src/foo.rs --message "tight coupling to the cache"
# See what's annotated on a file
qualifier show src/foo.rs
# After fixing it, resolve the annotation by id-prefix or location
qualifier resolve src/foo.rs --message "refactored to inject the cache"
```
## Available topics
Run `qualifier agents <topic>` for any of:
{{TOPICS}}
## Reference
For exact flag tables on any subcommand, run `qualifier <subcommand> --help`.
For the JSONL wire format and library API, see `SPEC.md` in this repo (if
present) or the published spec.