agent-context

---

Most AI context files are one of two things: empty scaffolds stuffed with [to fill] placeholders, or confident-sounding LLM boilerplate with no connection to actual code. Either way, they actively hurt. A 2025 ETH Zurich study found auto-generated context files reduced task success in 5 of 8 test settings and added up to 4 extra steps per task.

The problem is not the format. It is the evidence.

✨ What makes this different

Typical context tooling	agent-context
Generates plausible-sounding filler	Emits only what the graph supports
Requires manual editing of dozens of [to fill] slots	One [to fill] remains — Mock stance in testing.md — because that genuinely needs you
Safety rules live as polite markdown suggestions	Safety rules are wired as deny-list hooks in .claude/settings.json
One giant file loaded every session	Three-tier loading: always-on kernel, path-scoped rules, on-demand depth
Re-run to get the same scaffold again	Freshness check — warns when the graph is stale vs HEAD

🔄 How it works

 ┌─────────────────────┐     ┌──────────────────────────────┐     ┌────────────────────────────┐
 │     Your repo       │     │      Understand-Anything     │     │       agent-context        │
 │                     │     │                              │     │                            │
 │  src/               │     │  /understand                 │     │  /agent-context            │
 │  package.json  ──────────►│  knowledge-graph.json   ──────────►│  AGENTS.md                 │
 │  go.mod             │     │                              │     │  docs/agents/              │
 │  ...                │     │  /understand-domain          │     │  .claude/settings.json     │
 │                     │     │  domain-graph.json      ──────────►│  CLAUDE.md                 │
 └─────────────────────┘     └──────────────────────────────┘     └────────────────────────────┘
       your code                   real analysis graphs                  context files

Understand-Anything does the heavy lifting: it walks your source, identifies architectural layers, maps import relationships, and builds a dependency-ordered guided tour of the codebase. agent-context is a translator — it takes those graphs and renders them into the specific files AI agents read. The two tools are loosely coupled; you can regenerate either independently.

📁 Output at a glance

your-repo/
│
├── AGENTS.md                ◄── 🔑 the kernel  (<100 lines, loaded every session)
├── CLAUDE.md                ◄── 🔗 one-line shim: @AGENTS.md
├── CLAUDE.local.md          ◄── 🔒 gitignored personal prefs
├── CONVENTIONS.md           ◄── 🔄 Aider companion (synced from AGENTS.md)
│
├── .claude/
│   └── settings.json        ◄── 🛡️  deny-list hooks (rm -rf, force-push, .env writes...)
│
├── .cursor/rules/
│   └── agents.mdc           ◄── 🔄 Cursor rules (synced from AGENTS.md)
│
├── .github/
│   └── copilot-instructions.md  ◄── 🔄 GitHub Copilot (synced from AGENTS.md)
│
├── .codex/
│   └── instructions.md      ◄── 🔄 OpenAI Codex (synced from AGENTS.md)
│
├── .aider.conf.yml          ◄── 🔄 Aider config (points to CONVENTIONS.md)
│
└── docs/agents/             ◄── 📚 on-demand depth (loaded only when referenced)
    ├── architecture.md           project overview · stack · quick start · layer map · guided tour
    ├── flow.md                   entry points · business flows · execution paths
    ├── patterns.md               complexity hotspots · function exemplars · hub imports
    ├── glossary.md               domain vocabulary from the domain graph (or stub)
    ├── conventions.md            team coding standards (if CONVENTIONS.md exists)
    ├── testing.md                runner · file layout · single-test command
    └── tech-debt.md              known gotchas format (you fill this over time)

With --with-ci, two additional files are generated: