How are you managing decisions and specifications for coding agents?

[piaro]

I've been building several SaaS products, web apps, and native apps, both with teams and on my own. Though in reality, coding agents are doing most of the coding these days.

Especially in team development, implementation is moving much faster than before. At the same time, I feel that meetings and the way we agree on requirements and design haven't fully caught up with agent-based development.

This isn't a bad thing at all. Now that agents can write code so quickly, figuring out how to improve the productivity of everything else that becomes a bottleneck is a really interesting and important problem.

But I've also seen some real issues.

Different developers and their agents implement similar things in completely different ways. Code that looks reusable turns out to lack the essential commonality. Conventions that were followed at first gradually get lost in a growing number of documents. Agents fill in decisions that were never actually made, and those plausible assumptions become part of the code.

After going through this a few times, "How should we develop software well in this new environment?" has become a big question for me.

I've tried spec-driven development, AGENTS.md, rule files, ADRs, and putting more detailed documentation into the agent's context. They definitely help. But then I started running into another set of problems: the quality of the documents themselves, conflicting or outdated information, and deciding which information should be included in the context for each task.

That led me to wonder whether we need to think less about adding more human-oriented documentation, and more about the specific form of information that agents need to do their work safely.

That's why I started building the Agentic Development Framework.

The basic idea is simple: define the things that the repository currently holds true as Contracts, and have agents work against them.

A Contract records not only the rule, but also who had the authority to decide it and what evidence would show that the implementation satisfies it. When an agent encounters an unanswered decision, it should ask a person instead of silently filling the gap. The answer should remain in the repository rather than disappearing into a chat. After implementation, the result should be checked against the relevant Contracts and challenged independently.

This is clearly an extension of ideas that already exist: spec-driven development, ADRs, separating coding and review agents, and so on. I'm trying to rethink how those ideas fit together when agents are the main participants in the development workflow.

The project is still before its first release, and I don't know whether this is the right shape yet. Some parts may be too heavy, while other important parts may be missing.

So I'd really like to hear how other people are handling this:

• Have you run into similar problems with coding agents?
• How do you preserve requirements, conventions, and past decisions across agents and sessions?
• If you use specs, ADRs, AGENTS.md, or rule files, what works well and where does it start to break down?
• Does the approach in this repository feel too heavy for the problem?
• What am I missing?

Feedback on the idea, the README, or the design would all be very welcome. Critical feedback is completely fine too.

I'm Japanese, so my English may be a little awkward, but I'd still love to talk!