CooperativeAICoding
A framework that gives Product, Developers, and AI a single, shared way of working — so that software is built to clear objectives, within agreed technical guardrails, without the AI wandering off and burning tokens rebuilding things that already work.
Development is a team game, and normally this would involve Product working with Developers and Quality Assurance to build a good product, with continuous feedback from Product to Developers, Developers to Product, and QA to Developers and Product — all about capabilities, general product functionality, and look and feel.
The Problem
AI allows us to move faster, but this also means communication involves AI putting its own spin on the product, the coding, and how the QA is written. The plan of this framework is to make AI part of the team and stop AI from going its own way with a product.
AI when given vague or general descriptions tends to:
- get lost and add endpoints or features that weren't asked for,
- spend a lot of tokens creating, then recreating, the same work, and
- produce large-scale changes at high speed that overwhelm teams and destabilise production.
The goal is to give AI and all team members a source of truth for the product. Create guardrails around this so AI can build a solution that developers can maintain, following the Product flow, and also give AI a place to feed back what it cannot do. This also allows developers to keep to the idea of changing as little production code as possible and to use AI to create more testable code.
How It Works
The framework is defined in three areas:
- The Project brief, which is the why we are doing this, plus general development rules and structure, where each solution's code lives (including across multiple repositories), infrastructure/secrets policy, and gives AI the software engineering practices to employ and how the developers it is working with define these ideas.
- The solution specification, which is where developers define the reason for each solution, give AI the solution-specific guidance, and set it up to successfully move quickly — including its repo scaffold (file layout, tests, commands), its security rules, and the infrastructure and pipeline it needs. Solutions can start from named boilerplates (a scaffold preset plus a security baseline) in
template/_forms/boilerplates.json instead of being hand-written from scratch.
- The item — one page, one endpoint, or one database model — which defines the purpose of the single thing we are creating and what we need from it, and is designed to be built iteratively. Items can declare what must be built before them, so the AI never guesses at build order across a multi-solution project. AI can do the task and, instead of burning tokens trying to implement something it can't understand, it says "I can't implement this" and allows the developers to tell it how to implement it, or go to Product and rethink the feature.
Global Setup
Before any item is built, Product and Developers define the shared rules:
- Objectives & customers (Product) — what the software is for and who it serves.
- Technology & formats (Developers) — the tech stack, the platforms the solution must run on, and the formats it must support.
- Coding standards — general techniques the AI must follow (e.g. DRY, SOLID). Each standard must be defined: what it means here and how the AI should apply it.
- Frameworks — which global frameworks are in use and how they should be upgraded.
- Security — how users are authenticated, how endpoints are protected, and how permissions are enforced.
- Design — a place for Product to link UI/UX references, attach images or descriptions, and define their customers.
The aim of the technology rules is that any new endpoint the AI creates works with the target platform and is written so that build errors are less likely.
Items
Once the global setup is complete, the system is broken into sub-sections, and each sub-section is an item — the smallest thing this framework plans, builds and iterates. An item comes in one of three kinds, each with its own form:
| Kind | What it is | Form |
|---|
| Page | one screen, panel, or command group of a website or application | page.md |
| Endpoint | one API resource and its operations | endpoint.json |
| Model | one table or data model | database-model.json |
Nothing here assumes a front end. A backend-only project has no pages at all — it is endpoints and models, and everything below reads the same for them. Item is the word the commands already use: /new-item page|endpoint|model.
Each item also names the deliverable it works towards — see Deliverables, below.
Each item is defined once by Product, then built up iteratively by Developers — starting from the simplest working version and growing toward the final system one iteration at a time (changing data models, adding behaviour, and so on).
Item Layout
Product — fixed question (asked once):
- Why do we have this item? — the overall objective of this page, endpoint, or model.
Product — iterative questions:
- How should it look? (pages and screens)
- What information do we want to record?
- What are the use cases? Who uses this item, and how do they use it under different conditions?
- Who should be able to use it? (This sets the security expectations for developers.)
Product — and why it matters:
- What does this do for customers, and for the business?
Product plans these, with the AI if they like (/product), and signs them: sign-off 1.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
