Architecture file for coding agents: what to put in it, what it costs in context, and a CI check that keeps it true

# Architecture map

Backend is one Go module in `backend/`. Three binaries share `backend/internal/`.

## Who owns what

| Area | Owner | Entry point |
|---|---|---|
| HTTP API, routes | `backend/cmd/api` | `backend/cmd/api/main.go` |
| Background jobs, schedules | `backend/cmd/worker` | `backend/internal/worker/tasks.go` |
| MCP server | `backend/cmd/mcp` | `backend/internal/mcp` |
| Business rules | `backend/internal/service` | one file per domain |
| Database queries | `backend/internal/repository` | Ent, never raw SQL in services |
| Schema | `backend/ent/schema` | migrations in `backend/migrations` |
| Cache | `backend/internal/cache` | Redis, keys in `backend/internal/cache/keys.go` |

## How a request flows

Router in `backend/cmd/api/main.go` -> handler in `backend/internal/handler` (validates input) -> service (rules, auth checks) -> repository (Ent) -> Postgres. Anything slow is enqueued as an Asynq task and handled by the worker.

## Current vs legacy

- Current: outbound email goes through `service.NewEmailSender`. Legacy: building a Resend client directly.
- Current: task type `email:notification_digest`. Legacy: `email:weekly_digest`, kept only so queued tasks drain. Never enqueue it.

## Never

- Never query Postgres from a handler or a service. Go through `backend/internal/repository`.
- Never send email except through `service.NewEmailSender`.

## Deeper notes

Per-area notes in `.claude/rules/` load when the agent touches that area: background jobs, email.

---
paths:
  - "backend/internal/worker/**"
  - "backend/cmd/worker/**"
---

# Background jobs

- Task type names live in `backend/internal/worker/tasks.go`. One constant per task; the API enqueues with it and the worker handles it.
- Handlers are registered on the mux and schedules on the Asynq scheduler, both in `backend/cmd/worker/main.go`. Cron strings are UTC.

## Renaming a task type

Keep a handler registered for the old name for one deploy, so tasks queued before the deploy still drain. Example: `TypeNotificationDigestLegacy` (`email:weekly_digest`) points at the same handler as `TypeNotificationDigest`.

3. Measure what the files load

The map is the only part of an architecture file every session pays for, so count its tokens before committing it, with the model you run, because tokenizers differ by model. The Claude token counting endpoint takes the same body as a message:

jq -n --rawfile doc ARCHITECTURE.md \
  '{model: "claude-sonnet-5-5", messages: [{role: "user", content: $doc}]}' |
curl -s https://api.anthropic.com/v1/messages/count_tokens \
  -H "x-api-key: $ANTHROPIC_API_KEY" -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" -d @- | jq .input_tokens

Expected output for my map: 603. Every file I measured, with the root CLAUDE.md of the same repository for scale:

The counts include about 9 tokens of message wrapping. Two things stand out. The current tokenizer counts about 40% more tokens for the same text than Sonnet 4.5's, more than the "approximately 30 percent" the docs give. And my own CLAUDE.md costs about 25 times the map, so it is the file to trim first.

In money, the map is close to free: 603 tokens at Claude Sonnet 5.5's $2 per million input tokens is about $0.0012 a request, and a twentieth of that when cached. The real cost is behaviour. The ETH study found that developer-written context files raised the cost per task by up to 19%, and LLM-written ones by 23% on average, from the extra steps agents took following them.

4. Fail CI when the file names something that is gone

The drift check reads every architecture file, pulls out each backticked path, each backticked Go symbol and each paths: glob, and fails if the repository no longer has it. I found no open tool that does this: link checkers such as lychee check links and URLs, not paths in code spans, and architecture linters enforce rules in code without reading the docs. Save it as scripts/check-architecture.sh and make it executable with chmod +x:

#!/usr/bin/env bash
# Fails when an architecture file names a path, Go symbol or rule glob the code no longer has.
set -uo pipefail
shopt -s nullglob
docs=(ARCHITECTURE.md .claude/rules/arch-*.md)
stale=0
report() { echo "$1"; stale=$((stale + 1)); }
for doc in "${docs[@]}"; do
  [ -f "$doc" ] || { report "$doc: file is missing"; continue; }
  while IFS= read -r path; do
    [ -e "$path" ] || report "$doc: path $path does not exist"
  done < <(grep -oE '`[^` ]+/[^` ]+`' "$doc" | tr -d '`' | sort -u)
  while IFS= read -r sym; do
    git grep -qw "${sym##*.}" -- '*.go' || report "$doc: symbol $sym not found in any .go file"
  done < <(grep -oE '`([a-z]+\.)?[A-Z][A-Za-z0-9]+`' "$doc" | tr -d '`' | sort -u)
  while IFS= read -r glob; do
    [ -n "$(git ls-files -- ":(glob)$glob" | head -n 1)" ] || report "$doc: paths glob $glob matches no tracked file"
  done < <(sed -n 's/^  - "\(.*\)"$/\1/p' "$doc")
done
echo "$stale stale reference(s) in ${#docs[@]} file(s)"
[ "$stale" -eq 0 ]

On the Stackness repository it checks 31 references (23 paths, 4 symbols, 4 globs) in 0.3 seconds:

0 stale reference(s) in 3 file(s)

To see it fail, I added a row for collections, a feature removed on 27 August 2026, and pointed the email note at a file that does not exist:

ARCHITECTURE.md: path backend/internal/service/collection.go does not exist
ARCHITECTURE.md: symbol service.NewCollectionService not found in any .go file
.claude/rules/arch-email.md: paths glob backend/internal/worker/mailer*.go matches no tracked file
3 stale reference(s) in 3 file(s)

The glob check matters most: a rule whose paths: match nothing never loads, and nothing tells you. A deleted or renamed map fails too, with ARCHITECTURE.md: file is missing. Run the script on every pull request with GitHub Actions:

name: architecture-docs
on: pull_request
jobs:
  drift:
    runs-on: ubuntu-latest
    timeout-minutes: 5
    steps:
      - uses: actions/checkout@v4
      - run: scripts/check-architecture.sh

Kladov advised naming files but not linking them, because "links go stale". A check that fails the build is what makes naming exact paths safe. It cannot catch a file that still exists but now does something else, so keep a "last checked" date at the top of each file. In CLAUDE.md, put it in an HTML comment: Claude Code strips block-level comments from CLAUDE.md files before injecting them, so the date costs no tokens.

Check it worked

In Claude Code, run /context and check the list under Memory files for the map. Path-scoped rules load later, when a matching file is read; the documented InstructionsLoaded hook logs each load if you want proof. In Codex, run codex --ask-for-approval never "Show which instruction files are active." from the area's directory. Then start a fresh session and ask where a new scheduled task goes; the answer should name the three files from the note without a search first.

What goes wrong

Five failures are common with architecture files: the agent explores anyway, subagents never see the map, area notes vanish after compaction, Cursor skips the rule file, and Codex cuts long instructions. Each has a fix that takes a few minutes.

The agent still explores before editing

That matches the ETH finding: maps do not cut the steps before the first relevant file. Cut the tour and keep ownership, the legacy rules and the never list, which the code cannot tell the agent.

Explore and Plan subagents ignore the map

Claude Code's built-in Explore and Plan subagents start without CLAUDE.md, so they never see the map, though matching path-scoped rules still load for them. If a map rule must reach them, put it in the prompt you give them.

Area notes disappear after compaction

Path-scoped rules and nested CLAUDE.md files are summarised away by compaction and come back only when a matching file is touched again. A rule that must survive goes in the map.

Cursor never applies the rule

Cursor reads only .mdc files in .cursor/rules. Rename the file or move the text into a nested AGENTS.md.

Codex drops the end of the instructions

Codex stops adding AGENTS.md files at 32 KiB by default. Its two doc pages disagree on whether the cap is per file or for all files combined, so keep the total under it.

Checklist

• Map of 30 to 40 lines: ownership table, one request-flow line, current versus legacy, a never list.
• No directory tour.
• One note per area, loaded by a path trigger rather than a model decision.
• Map counted with the token API; root CLAUDE.md counted too.
• scripts/check-architecture.sh passing locally and running on every pull request.
• Last-checked date at the top of each file.

This is the context engineering move applied to architecture, and a narrow case of treating the context window as scarce. For which instruction belongs in which file, see AGENTS.md vs CLAUDE.md vs skills; for the AI tools developers pair with their agents, see the category page.