(Experiment) Colocating agent instructions with eng docs

10 months ago

The author experimented with embedding AI agent instructions within internal engineering documentation instead of maintaining separate agent docs.
Instructions for AI agents were embedded as comments in the documentation file, which are invisible to human readers but accessible to agents.
The experiment involved converting a code example into a buildable and testable example using the embedded instructions.
Gemini CLI successfully followed the instructions, including creating a failing test first and then fixing it.
The experiment revealed a mistake in the instructions, confirming that the agent was closely following them.
The author notes that the experiment was informal and suggests that having both agent docs and targeted instructions might yield the best results.
The process included updating build files for Bazel, GN, and CMake, and verifying that the documentation build still works.

Hasty Briefsbeta