I had a lot of issues with spec-driven approaches, agents are too readily producing fluff, large projects have so many specs agents start making mistakes maintaining them. There's a constant consistency tax. In the end every spec is just a bunch of facts, so I decided to leave that and throw away everything else while making it friendlier for agentic use. Introducing facts - skills and CLI for agents to use facts-driven development. https://github.com/av/facts |
Outside of that, I found a few things particularly useful so far: - I can seed a relatively complex project with just a few core assumptions about behaviors I have, agent will firgure out all the gaps in a formalised way - I can easily diff/compare the fact sheets against one another. One example: I built a fact sheet for a fairly hairy Python CLI, then asked the agent to update all Python-related entries to their Rust equivalents, then rebuilt this CLI in Rust in the scope of another project - It's much quicker than working with large spec formats, agent uses less tool calls to capture the context it needs to work on something - After doing large refactoring, agent doing a "fact check" is essentially a full on e2e test run
Two biggest gains for agentic use are because fact sheets are more compact and that they are all assertions about the desired state, it's much easier to reason about things that should and shouldn't be there
Spec is essentially a set of facts + fluff. List of facts is essentially the spec minus the fluff. This was my main idea when trying this approach out. It worked quite well, so I went on building the CLI and a set of skills to better guide the agent about this specific workflow.