Vortex vs AGENTS.md: when to use which

These two things get pitted against each other, and it is a false fight. AGENTS.md and Sonar Vortex solve different problems at different layers of the loop. AGENTS.md is a static file of team conventions your agent reads as context. Vortex is live, structured code intelligence delivered at the moment the agent writes, plus a deterministic check after. You want both, and once you see where each one's ceiling is, the division of labor is obvious.

This guide shows the mental model, the one Claude Code detail most posts get wrong, and a tested setup that runs both in the same repo.

What is the difference between AGENTS.md and Sonar Vortex?

• AGENTS.md / CLAUDE.md: plain Markdown you write once and maintain by hand. Loaded into the agent's context at session start. Good for stable facts a new teammate would need: build and test commands, PR conventions, code style, project layout. It is guidance, not enforcement.
• Sonar Vortex: two capabilities wired into the agent's inner loop. Vortex Context Augmentation injects your project's real guidelines, architecture graph, and dependency health at generation time. Vortex Analysis runs SonarQube's engine on each change and feeds findings back. It is enforcement and live intelligence, derived from analysis, not from a file you keep updated.

Different layers. One is a README the model reads; the other is a check the model cannot talk its way past. Keep reading for exactly what belongs in each.

First, the Claude Code detail almost everyone gets wrong

If you use Claude Code, know this before you do anything else: Claude Code reads CLAUDE.md, not AGENTS.md. That is straight from Anthropic's memory docs. If your repo already has an AGENTS.md for Codex, Cursor, or Gemini CLI, Claude Code will not read it on its own. Bridge it.

The documented, no-duplication way is a one-line import in CLAUDE.md:

@AGENTS.md

## Claude Code
- Use plan mode for changes under `src/billing/`.

Claude loads the imported AGENTS.md at session start, then appends any Claude-specific notes below it. A symlink works too if you have nothing Claude-specific to add:

ln -s AGENTS.md CLAUDE.md

On Windows a symlink needs Administrator or Developer Mode, so prefer the @AGENTS.md import there. Everything this guide says about "AGENTS.md" applies to CLAUDE.md in a Claude Code repo; the import just makes one file serve every agent.

What is the static file genuinely good at?

AGENTS.md is a real standard, not a hack. It is "a simple, open format for guiding coding agents," a "README for agents," used by over 60,000 open-source projects and stewarded by the Agentic AI Foundation under the Linux Foundation. Keep it, and keep it lean and operational:

# AGENTS.md

## Setup
- Install: `pnpm install`
- Dev server: `pnpm dev`

## Tests and checks
- Run tests: `pnpm test`
- Lint and types: `pnpm lint && pnpm typecheck`
- All three must pass before opening a PR.

## Conventions
- TypeScript strict mode; single quotes; no semicolons.
- API handlers live in `src/api/handlers/`.

## Pull requests
- Title format: [<area>] <summary>
- Keep diffs under ~400 lines where you can.

That is the sweet spot: stable commands and conventions, the stuff that rarely changes and that a human should own. Two rules from Anthropic's own docs keep it effective:

• Keep it under 200 lines. "Longer files consume more context and reduce adherence." A bloated conventions file is a worse conventions file.
• Treat it as guidance, not a guarantee. CLAUDE.md and AGENTS.md are "loaded at the start of every conversation" and Claude "treats them as context, not enforced configuration," with "no guarantee of strict compliance, especially for vague or conflicting instructions."

That second point is the whole ballgame, and Anthropic says it out loud.

Where the static file hits its ceiling (Anthropic agrees)

You do not have to take a vendor's word that prose files have limits. The Claude Code docs draw the line themselves, three times:

1. For anything that must happen every time, use a hook, not prose. "If the instruction is something that must run at a specific point, such as before every commit or after each file edit, write it as a hook instead. Hooks execute as shell commands at fixed lifecycle events and apply regardless of what Claude decides to do." A line in AGENTS.md that says "always run the analyzer after editing" is a wish. A hook is a guarantee.
2. Do not hand-maintain your architecture in prose. The /doctor cleanup deliberately "cuts content Claude can derive from the codebase, such as directory layouts, dependency lists, and architecture overviews." Architecture written by hand goes stale between merges, and the tooling will tell you to delete it.
3. Conflicting instructions get resolved arbitrarily. "If two files give different guidance for the same behavior, Claude may pick one arbitrarily." The more you cram in to cover edge cases, the more you invite contradiction.

So three jobs a static file cannot reliably do: enforce a rule on every edit, hand you your current architecture and allowed dependencies, or verify a change against your actual quality gate. Those are exactly the three jobs Vortex is built for.

How does Sonar Vortex enforce code quality on every AI agent edit?

Sonar frames its loop as Guide, Verify, Solve. AGENTS.md lives entirely in your head before "Guide." Vortex lives inside the loop:

Guide (Vortex context augmentation). Before the agent writes, it injects, scoped to the task at hand:

• coding guidelines pulled from your project's own history of issues, not a generic style list;
• your actual architecture graph plus user-defined intended constraints, so the agent builds within your design instead of a paragraph describing it;
• semantic navigation over ASTs and control flow, so the agent finds the right code by meaning rather than grep;
• dependency health, so a package is checked for known vulnerabilities, supply-chain malware, and license issues before it is added.

None of that is prose you maintain. It is derived from analysis and current by construction.

Verify (Vortex Analysis). After each edit, SonarQube's engine analyzes the change with full CI-level insights and feeds findings back to the agent. On Claude Code this ships as a PostToolUse hook, which is precisely the "use a hook for must-run-every-edit" mechanism the Anthropic docs point you to.

How do I use AGENTS.md and CLAUDE.md together in the same repo?

Here is a setup you can reproduce. It layers the static conventions file and the live intelligence without either stepping on the other.

1. Write a lean AGENTS.md and bridge it to Claude Code

Use the AGENTS.md above. Then, in the repo root:

# Option A: import (works everywhere, lets you add Claude-only notes)
printf '@AGENTS.md\n\n## Claude Code\n- Use plan mode for changes under `src/billing/`.\n' > CLAUDE.md

# Option B: symlink (macOS/Linux; nothing Claude-specific to add)
ln -s AGENTS.md CLAUDE.md

2. Add Vortex

With the SonarQube CLI installed and authenticated, from the repo:

sonar integrate claude --project my-org_my-app

This configures Claude Code for the project, installs the secrets-scanning hooks (a UserPromptSubmit hook and a PreToolUse hook). Vortex analysis `PostToolUse` hook and Vortex context augmentation require SonarQube Cloud (Team annual or Enterprise) plus a Sonar Agent Essentials subscription, project-scoped. Restart Claude Code so the hooks and MCP config load.

Prefer to own the verify hook instead of the managed one? It is five lines of logic. .claude/hooks/sonar-verify.sh:

#!/usr/bin/env bash
# runs after Claude edits a file; Claude Code passes the event as JSON on stdin
input=$(cat)
file=$(printf '%s' "$input" | jq -r '.tool_input.file_path // empty')
[ -f "$file" ] || exit 0
out=$(sonar analyze agentic --file "$file" --format text); rc=$?
case "$rc" in
  0)  exit 0 ;;                                          # clean
  51) printf '%s\n' "$out" >&2; exit 2 ;;                # issues: feed them back to Claude
  *)  printf 'SonarQube could not analyze %s (exit %s); not verified.\n%s\n' "$file" "$rc" "$out" >&2
      exit 2 ;;                                          # analysis failed: surface it, do not pass silently
esac

Wire it in .claude/settings.json:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/sonar-verify.sh", "timeout": 120 }
        ]
      }
    ]
  }
}

sonar analyze agentic exits 51 when it reports issues and 0 when clean, so the hook branches on the exit code, feeds findings back on 51, and refuses to pass silently if the analyzer itself failed.

3. Confirm what loaded

In Claude Code, run /context to confirm your CLAUDE.md (and the imported AGENTS.md) are in context. 

AGENTS.md vs Sonar Vortex: which handles which concern?

Read the table as a rule of thumb: if it is stable, human-owned, and portable, it belongs in AGENTS.md. If it is live, structural, or must be enforced, it belongs to Vortex.

A concrete example

Task: "Add a refund endpoint to the payments API."

AGENTS.md does its part. The agent knows to put the handler in src/api/handlers/, run pnpm test and pnpm lint, and title the PR [payments] Add refund endpoint. That is real value and none of it needed a model to be clever.

What AGENTS.md cannot do: tell the agent that only PaymentService is allowed to reach the database, that there is a history of injection issues in this area, or that the sql-template package it is about to add has a known advisory. Context Augmentation supplies the architecture constraint and the relevant guidelines up front, and check_dependency vets the package before it lands in package.json. Then the agent writes something like "SELECT * FROM refunds WHERE id = " + id, the PostToolUse hook runs sonar analyze agentic, and SonarQube returns a javasecurity:S3649 SQL-injection finding on that line. The hook exits 2, the finding goes back to the agent, and it switches to a parameterized query before the code ever reaches review. A prose rule saying "avoid SQL injection" was in a hundred repos before this one. The deterministic check is what actually stopped it.

What are common mistakes when using AGENTS.md with AI coding agents?

• Do not turn AGENTS.md into a rulebook and expect enforcement. Pasting "always write secure code, follow our architecture, reuse existing utilities" into a Markdown file feels productive, but the docs are explicit that it is context with no guaranteed compliance, and adherence drops as the file grows. Keep those concerns where they are enforced: Sonar rules, the architecture graph, and the verify hook.
• Do not maintain the same thing in both places. If Vortex is supplying live guidelines and architecture, do not also hand-write them into AGENTS.md. They will drift apart, and conflicting instructions get resolved arbitrarily. Let the file hold what is stable and human; let Vortex hold what is live and structural.

Bottom line

This was never Sonar Vortex versus AGENTS.md. AGENTS.md is your portable, human-written conventions file: how to build, test, and ship this project, in under 200 lines, read by every agent you use. Sonar Vortex is the live code intelligence and the deterministic check: what the code should look like given your real architecture and history, verified on every edit by a hook the model cannot argue with. Use the file for what is stable and human. Use Sonar Vortex for what is live and must be true. Together they cover the whole loop; apart, each leaves exactly the gap the other fills.