My Pain Point
Doing spec-driven development with AI agents, I quickly ran into a problem: managing all the artifacts they produce. Brainstorming notes, architecture designs, specifications and contracts, results of architecture and code reviews, troubleshooting notes, etc. Even on a small project you quickly end up with hundreds of markdown files. On a team project, thousands to tens of thousands.
The basic approach is to store them in a folder in the repo (e.g. docs/ ), with an index.md file listing each file with a short description of its content. This approach has several issues:
Documentation pollutes your code base
Publishing an artifact goes through the same PR review as code, which makes code reviews harder and sharing artifacts between team members have to wait the PR review
It is unrealistic to capture the content of an ADR or a spec in a 1-2 sentence description in an index file, so agents can't rely on it to find the right information
You can't share information across teams (e.g.…