Skip to content

Semantic Density Optimization for Agent Codebases

Semantic density optimization maximizes task-relevant tokens for agents — cut structural ceremony while preserving naming, docs, and commit context agents cannot cheaply reconstruct.

Related lesson: Signal Per Token covers this concept in a hands-on lesson with quizzes.

The compression paradox

Compressing codebase content for agents backfires. A controlled experiment on log format (Ustynov, 2026) shows why:

Format Input tokens Session tokens Session/file ratio
Human-readable 8,072 18,900 2.3×
Structured 7,106 24,000 3.4×
Compressed 6,695 31,600 4.7×

The compressed format cut input tokens by 17% but raised total session cost by 67%. Removing semantic content shifts the interpretive burden to the reasoning phase, so the model reconstructs meaning it could have read directly. Optimize for semantic density, not raw token count.

What semantic density means

Semantic density is the ratio of task-relevant tokens to total tokens. Every token in a codebase is one of two kinds:

  • High-density: meaning the agent cannot derive without extra inference, such as descriptive names, type annotations, docstrings, error messages, and commit reasoning
  • Zero-density: structural overhead the agent must parse but gains nothing from, such as boilerplate, dependency injection wiring, framework scaffolding, and ceremonial access modifiers

The goal is to remove zero-density tokens while protecting high-density ones.

Seven conventions to reconsider

Ustynov (2026) analyzes seven human-centric conventions under agent consumption.

1. Naming conventions

Descriptive names are high-density tokens. An agent reads VerifyOrderByAvailableAmount directly, but verifyOrd forces it to infer meaning from usage. Strengthen naming for agents. Abbreviations that save keystrokes for humans cost reasoning tokens for agents.

2. Commit messages

The conventional 50-character limit works against agents. When an agent traces history to understand why code exists, terse messages force more turns of clarification. Include the reasoning, the rejected alternatives, and the constraints. Otherwise the agent reconstructs them through many file reads.

3. Abstraction depth

Deep call hierarchies force agents to traverse many files per task. Flat call chains with well-named functions reduce cross-file navigation. Enterprise frameworks that spread one request across many scaffolding layers make agents pay that read cost on every lookup.

4. File splitting

Human cognitive limits drive the convention of keeping files small. Agents do not share this limit, but they do pay a navigation cost per file. Let deployment boundaries and logical cohesion drive file organization, not human screen capacity.

5. SOLID principles

Single-responsibility and interface-segregation rules that split logic into micro-units raise agent traversal cost. Apply them where they serve logical boundaries, not where they serve human reading habits.

6. Logging formats

Structured log entries with readable field names beat abbreviation-heavy formats. An agent reads "Payment failed for order #4521: insufficient funds" directly. "|E|PS|pf|o=4521|rs=insuf_funds" forces it to decode abbreviations, which costs reasoning tokens.

7. Classical anti-patterns

Anti-patterns like the God Object emerged to protect human cognition. Under agent consumption, gathering related logic into fewer files reduces cross-file traversal. This trade-off lacks empirical validation. The paper flags it as theoretically motivated but unconfirmed. Attention degradation on very large files is a documented LLM limitation (Liu et al., 2024). The paper does not measure it here, so treat this as provisional.

The program skeleton artifact

The paper proposes a new artifact — a CODEMAP.md file — stored at the repository root:

# CODEMAP.md

## Module Topology
- `src/payments/` — payment processing pipeline
- `src/orders/` — order lifecycle management

## Entry Points
- `payments/processor.py:process_payment(order_id)` — main payment flow
- `orders/validator.py:validate_order(order)` — pre-payment validation

## Key Call Chains
1. API → `process_payment` → `validate_order` → `charge_card` → `emit_event`

## Data Flow
Order ID → validation → payment charge → event emission → status update

This gives batch-oriented navigation in a single read. Language Server Protocol queries return one symbol at a time. A program skeleton instead gives agents the codebase topology before they explore, which reduces the file reads needed to understand task context.

Example

A logging statement shows semantic density directly.

Before, compressed and low-density: 

log.e(f"|PS|pf|o={oid}|rs={rs}")

After, readable and high-density: 

logger.error(f"Payment failed for order #{order_id}: {reason}")

The compressed version uses fewer input tokens per log line, a real but modest saving. When the agent reads this log during debugging, it must decode PS, pf, and the abbreviated field names. That spends more reasoning tokens than the original saving. The agent reads the readable version straight away, with no decoding step.

When this backfires

Semantic density optimization trades human ergonomics for agent performance. The trade-off is not always worth it:

  • Human teams dominate the workflow: if agents touch the codebase rarely, for code review, one-off generation, or occasional queries, tuning conventions for agents degrades the daily experience of the developers who live in the code
  • Single-study basis: the evidence comes from one controlled experiment on log formats (arXiv:2604.07502), so applying its conclusions to naming conventions, file structure, and SOLID principles is an extrapolation the paper calls theoretically motivated
  • Flatter files create their own problems: gathering logic into fewer large files reduces agent traversal cost but raises merge conflict frequency, complicates code ownership, and may exceed the model's attention range on very large files
  • Context window sizes are growing: as models handle larger windows with better long-range attention, the navigation advantage of flatter structures shrinks, and human-oriented organization may win again

Key Takeaways

  • Before compressing a format to cut input tokens, measure total session cost — a 17%-smaller format raised it 67% in the cited experiment
  • Classify each line as zero-density (cut freely) or high-density (the agent cannot reconstruct it) before trimming — the wrong cut is what causes the cost blowup
  • Apply naming, commit-message, and abstraction changes where agents read the code often, not as a blanket rewrite — human teams still pay the ergonomics cost
  • Add a CODEMAP.md at the repo root with module topology, entry points, call chains, and data flow — read once instead of exploring file by file
  • Flatter files cut agent traversal cost but raise merge-conflict frequency and risk exceeding a model's attention range on very large files — weigh both before consolidating
Emerging — single recent source Last reviewed: 2026-06-13