Best practices

How to roll Atmos out on a real codebase, from the first local scan to the CI gate and the agent hook.

Scan where the work happens#

Findings get fixed when they appear while the code is still open. Run Atmos at every point where code changes:

• In the editor. The extension rescans on save and puts findings inline.
• After every agent turn. The scan hook hands findings straight back to the agent that introduced them.
• On every pull request. The CI gate below, plus the check and comment on the pull request with the GitHub App connected.

Rescans after an edit recheck only what changed and finish in under a second, so pass --incremental everywhere a tree is scanned repeatedly. In CI, a cold scan of the whole tree is usually right. See warm scans.

Gate every change in CI#

Run the same atmos scan . locally and in CI, and let the exit code decide the build. Fail the build on findings and on every error code, from a scan error to a failed license check or a failed upload.

Treat rules as code#

Project rules belong in .atmos/rules/, committed and reviewed like everything else. See what to commit. A security decision expressed as a rule has a diff, an author, a review thread and a revert button. Encode the conventions that are yours alone: which middleware guards routes, which query builder is sanctioned, which directories may touch the filesystem.

Tune to zero false positives#

When a rule fires on code that is fine, fix the rule instead of teaching the team to ignore it. Exempt the approved case inside the rule or with a marker that is visible in the code, so the intent survives review. Testing and tuning shows the shapes. When a flow you expected is not reported, run with -v.

Prioritize by reachability#

Most dependency alerts are about packages your code never reaches. Gate pull requests with --reachable-only and keep the complete report on the dashboard, where EPSS scores sort the backlog. --min-severity and --min-confidence tighten the gate further.

Protect your credentials#

On your own machine, atmos login stores a sign-in that only that machine holds. Sign out with atmos logout before handing a machine on, and revoke any device you no longer recognize from the Tokens page. In CI, anyone holding your Workspace Token can scan against your workspace: keep it in ATMOS_TOKEN as a CI secret rather than on a command line, where it would land in shell history and process lists, and rotate tokens freely. See sign-ins and the Workspace Token and what leaves your machine.