IDEA.Md

IDEA.md — A Standard for Portable Idea Intent in Agentic Software

**IDEA.md** is a vendor-neutral file standard for expressing *what to build and why* before any code is written. It is the upstream intent document for AI coding agents — designed to sit above `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, and Copilot instruction files in the project hierarchy. Where those files tell agents how to behave in a repo, `IDEA.md` tells them what the idea actually is.

Inspired by Andrej Karpathy's [idea file concept](https://x.com/karpathy/status/2040470801506541998): in an era where AI agents can build anything from a prompt, the scarce resource is knowing what to build. Share the idea, not the code. The other person's agent customizes and builds it for their specific needs.

---

Why IDEA.md Exists

AI coding agents like Claude Code, OpenAI Codex, Gemini CLI, and GitHub Copilot already have instruction files for agent behavior. But there is no broadly adopted, vendor-neutral file for the idea itself — the product thesis, problem framing, solution shape, and boundaries.

`IDEA.md` fills that gap. It is the source-of-truth file for product intent in any agentic software project.

How It Works

Every project gets one root-level `IDEA.md`. It has five required sections:

Section	Purpose
Thesis	One or two sentences capturing the core idea
Problem	What's broken today and for whom
How It Works	The pattern and key insight — not the implementation
What It Does Not Do	Boundaries that prevent scope creep and overbuilding
Where To Start	A nudge for agents to begin collaborating with the user

Optional sections (add when they earn their place): Why Now, Who Benefits, Constraints, Risks, Open Questions, Success Criteria, Context and References.

The file is intentionally abstract. It describes ideas, not implementations. The agent and the user figure out the specifics together.

Quick Start

1. Copy [`ID