Keeping Specs in Repo Isn't Always Useful for Agents

zeeg · x · 2026-07-14

The author shares findings from their experiment of keeping specs long-term in the repo for co-location: it didn't provide enough value.

The main issues are:

High maintenance overhead, with much content devolving into documentation rather than executable constraints
Frequent updates lagging, causing agents to misjudge the "source of truth"
Even when intent is documented, models often ignore it, leading to more manual copy-pasting

They plan to transition to a lighter structure:

policies/: Only for very lightweight rules, like where code comments should go
openspec/: Kept temporarily, but no longer used as context docs
custom skills: To supplement third-party docs, like Vercel Sandbox and Slack API
agents.md: Serves primarily as a resource map
Using inline code comments to express intent

More from coding & agent