Using a behaviour index to help AI coding agents explore your code
A 'behaviour index' is a Markdown file (BEHAVIOR.md) auto-generated from test names and file locations that helps AI coding agents and humans navigate a codebase. Instead of searching raw code lines (expensive in tokens) or file paths (low information density), agents search the behaviour index to quickly understand what a concept means in the app and where its implementation lives. The post compares token costs across three search strategies using the Codex CLI repo, shows how to generate the index via test reporters or regex scripts, and covers limitations like weak test suites, parameterised test names, and agents that ignore custom search instructions. Optimisation tips include embedding code symbols in test names and maintaining separate AI and human versions of the index.
