I’ve been using a “deep init” style setup with coding agents —
each directory has its own README.md / AGENTS.md describing roles and constraints.
It works well early on.
But as the codebase grows, those docs inevitably drift,
while the agent still treats them as ground truth.
That creates a subtle reliability issue:
the model is following instructions — they’re just stale.
To experiment with this, I built a small tool called VeriContext.
When documentation references code, it embeds a SHA-256 hash of the exact snippet (inside an HTML comment, so rendered Markdown stays clean).
On verification, either the hash matches or it fails (fail-closed, no fuzzy matching).
It can run:
• as an agent skill (verify before finishing a task / committing), or
• via pre-commit / CI (e.g. npx vericontext verify workspace …)
The goal isn’t better prompting — it’s constraining documentation to stay aligned with code.
I’m curious how others are handling doc / context drift when using Codex or other coding agents.
Would strict fail-closed verification feel too rigid in practice?
Has anyone tried AST-aware approaches instead of raw snippet hashing?
That’s a great idea — I hadn’t considered using short commit hashes.
My only concern is that a file-level commit hash could change even if the referenced snippet is still valid, which might lead to hash-only doc updates without any real change in meaning.
Personally, if I have to do much manual work to “help” the AI then I should just ask the AI to help me help it. Maybe ask Codex to plan and setup an automation for you that keeps the docs in sync.
I did something minor that’s somewhat similar: In my global AGENTS.md I asked to add a short random code to each of its findings after a review. That way I can refer to them further down a conversation and keep track of the changes related to each finding etc.