Software Architecture Blog
Conserving Context in Projects Built with AI
One gotcha in building software with agentic tools is context consumption. Models get dumber the fuller their context gets, and context heavy operations can result in failed compaction, or even API errors that poison your whole session.
If you have lots of tests -- that's good! But test output can sometimes get obnoxiously long, which starts to cause problems.
With a bit of upfront design, you can structure your project so agents work efficiently by default, seeing only what they need, while full diagnostic detail is always available to dig in to.
Below is a reusable prompt you can give to an agent to retrofit this capability onto any existing project. Be aware that this will change the flags used by your project. Don't take the following as-is…instead customize it to fit your use case.
Token-efficient logging
Add a structured log-level system to this project so that agents can invoke tools with minimal token consumption while full diagnostic detail is always available when needed. Take into account differences between things intended for running client-side (for action or remediation-orientated message) vs post-analysis.
The core idea: separate console and file sinks with independent level filters. Agents run commands at SUMMARY level (outcomes only, a few lines). A human debugging runs at INFO or DEBUG. Agents use grep on files rather than huge context.
Full trace is always written to a file for later inspection.
Log levels to implement (ordered by severity):
TRACE=0 DEBUG=1 INFO=2 SUMMARY=3 WARN=4 ERROR=5 FATAL=6
SUMMARY is not just a filter threshold — call sites at SUMMARY level must also minimise line length. Use short prefixes (emoji may work well), abbreviate labels, omit context that can be readily inferred. Goal: grep '^<prefix>' on full output gives a complete decision audit in under 10 lines per run.
Runtime configuration:
--console LEVEL stdout filter default: SUMMARY
--file LEVEL file filter default: NONE (disabled) unless -o present
-o PATH output file path default: output/last.log
Rule: -o without --file implies --file DEBUG
Rule: --file (not NONE) without -o uses output/last.log
Environment variables (lower precedence than CLI flags):
APP_CONSOLE_LEVEL
APP_FILE_LEVEL
APP_OUTPUT_FILE
Used by test runners to set INFO without touching generated test harnesses.
Call site classification guide:
┌──────────────────────────────────────────────────────────────────────────┬─────────┐
│ What │ Level │
├──────────────────────────────────────────────────────────────────────────┼─────────┤
│ Lowest-level details of inner operations │ DEBUG │
├──────────────────────────────────────────────────────────────────────────┼─────────┤
│ Control flow / decision, intermediate results, important configuration │ INFO │
├──────────────────────────────────────────────────────────────────────────┼─────────┤
│ Things going wrong, unexpected-but-non-fatal conditions │ WARN │
├──────────────────────────────────────────────────────────────────────────┼─────────┤
│ Non-fatal failures │ ERROR │
├──────────────────────────────────────────────────────────────────────────┼─────────┤
│ Final decisions and outcomes only, in short prefix format │ SUMMARY │
└──────────────────────────────────────────────────────────────────────────┴─────────┘
Volume reduction: Be aware of chatty log messages, and reduce chattiness.
SUMMARY line format:
- Must be greppable
CLI binary changes:
- Flags: --console, --file, -o flags before positional args so existing invocations are unaffected
- Defaults: console=SUMMARY, file=NONE (or =DEBUG if -o present)
Test runner changes:
export APP_CONSOLE_LEVEL="${APP_CONSOLE_LEVEL:-INFO}"
Sets INFO as the default for test runs (algorithm flow visible, per-iteration dumps suppressed) while letting the caller override.
Repository hygiene:
- Add output/ to .gitignore
- Create output/.gitkeep so the directory is tracked but contents are not
AGENTS.md additions — add these two sections so future agent instances know how to invoke efficiently:
## Token-efficient invocation
Include examples of CLI invocation using limited stdout & more detailed file output
Prefer redirecting to output/ and grepping rather than reading full output inline.
output/ is .gitignore'd.
## Document specific output grep patterns for specific purposes
Verification checklist after implementation:
1. Default invocation → stdout shows only SUMMARY lines + final result block
2. -o output/last.log → same stdout + full DEBUG in file
3. --console DEBUG → verbose output to stdout
4. Env var APP_CONSOLE_LEVEL=INFO → INFO+ on stdout
5. Test runner → INFO-level output by default
6. All existing tests still pass
---
The key invariant: Agents should never need to read more than ~10 lines of output to know whether a run succeeded and what the outcome was. Any exceptions need to be discussed with the maintainer before implementing
More broadly, this is a chance to think about ways in which agentic development is subtly different than what millions of developers are used to.
Embrace this kind of thinking alongside a community of practitioners. Subscribe to the Architect+ Digest.
"I put my name on everything I do"