AI Development Methodology

AI Development Methodology - run a software project when some of your contributors are AI agents

AI Development Methodology

How to run a software project when some of your contributors are AI agents - and one of them just panic-refactored your auth middleware at 2am while a different one was halfway through the same task.

Fourteen short docs. Markdown + git. No SaaS, no signup, no vendor lock-in. An AI agent picks up the operating contract in seconds via templates/ or a one-line skill install. A human grasps the core concept in 5 minutes via the CHEATSHEET. Full reading is a focused day. Use forever (or until you find something better).

By Miklós Polgár (polgarmiklos@gmail.com) - CC BY 4.0. Fork it, ship it, charge for it, teach it. Just keep the credit.

TL;DR

Four planning layers - strategy → pillars → epics → items. Each answers a different question.
Three discipline overlays - working principles, Definition of Done, lessons-learned memory. They bind every change.
File-based locks with TTL so two AI agents (or two humans) don’t both grab the same item.
Fix-test loop for the actual UI because “tests pass” doesn’t mean “the page renders.”
Cross-AI validation + user testing as the final gates.
Work survives the handoff - an approved goal is frozen against silent rewording, and at Effort M+ the item body carries the planning session’s findings so a cold session can pick it up.
Autonomous goal-oriented development cycles - paste-and-adapt AUTONOMOUS_LOOP.md prompt drives multi-hour unattended runs toward named milestones; tiered autonomy on authoritative artifacts (cosmetic auto-patch with cross-AI diff-verify; substantive maintainer-authored).
Milestone-driven deep-eval every Nth loop iteration - 0–10 rubric per area; unsolvable issues get handled/postponed/marked after a default 3-attempt cap, never forced.
Plan before non-trivial work. Use your tool’s plan mode.
Battle-tested in one production project + self-applied (see self-development/, and what that instance actually adopts). Use the latest content: v1.36.0 preview, including v1.35.0. Both remain unreleased; v1.34.0 is the older latest tag. See distribution status.
Quick reference: CHEATSHEET.md. Worked example: examples/.

Install

As an agent skill - one command. Gives your coding agent on-demand access to the methodology’s operating rules - Definition of Done, the lock protocol, the Status/Test values, the ROI picking rule, the AI-safety rule - with links into the full docs. Uses the Agent Skills format. The community skills CLI installs into supported clients; client behavior needs its own verification. To install the latest default-branch content (currently the unreleased v1.36.0 preview):

npx skills add Korner83/ai-development-methodology

Then ask process questions naturally or use the client’s explicit skill invocation. The skill contains only Markdown; the external installer runs software. The command follows main; use the commit-pinned latest-content command for a reproducible snapshot. Source · version and compatibility notes.

The portability comes from the format rather than the installer: the skill is written in the Agent Skills open format - a SKILL.md carrying name and description frontmatter - so any client that reads that format can load it, with or without the CLI. Copying the folder in by hand works too.

As a project scaffold - full structure. To drop the methodology docs plus a project-instruction file into a new project (strategy → pillars → epics → backlog), follow How to use it → Step 1. Everything is files you copy; there is nothing to build or install.

How it fits together

Four planning layers cascade downward; three disciplines bind every change at every layer; three operational supports make the daily work navigable.

Four planning layers, three disciplines, and three operational supports.

Diagram source

For the file layout and how the cascade physically lives on disk, see How the work cascades below.

What you get

After a week or two:

The backlog stops lying. Status: done requires Test: pass. No partial credit, no judgment calls.
Agents stop colliding. File-based locks with TTL do the coordination that “I’ve got this” in chat never did.
The goalposts stay put. Approve what “done” means and agents can’t quietly reshape it to fit what they built - the one drift that’s invisible in a diff.
Handoffs stop amnesia. What the planning session learned lands in the item, so the next session doesn’t rediscover it.
The same mistake stops coming back. Memory turns a recurring fix into a one-time cost.
Nothing is locked in. Markdown and git. If your AI tool is gone in 18 months, your process isn’t.

Why this exists

Most projects accumulate the same failure modes once they last more than a few weeks. AI-assisted projects accumulate them twice as fast - the effective contributor count doubles and the new contributors don’t sleep.

The problem	How this set closes it
Direction drifts; every quarter re-litigates “what are we building?”	Strategy docs - versioned phases with exit criteria.
“Done” means whatever the contributor decides.	Definition of Done - six binary gates; hard rule `Status: done` requires `Test: pass`.
“Tests pass” but the page is white, dark mode broken, auth bypassed.	Actual-UI fix-test loop with required dimensions.
Lessons evaporate; same mistake every six months.	Two-layer memory - instruction file + memory directory.
Parallel contributors collide; two agents grab the same item silently.	File-based locks with TTL - humans and agents, same protocol.
AI agents wander off-task - speculation, scope creep, “while I’m here” refactors.	Working principles - distilled from real LLM failure modes.
AI agrees with you and you’re both wrong.	Challenge before consenting.
AI writes broken code AND broken tests that validate it.	Cheating agent anti-pattern + cross-AI validation.
The agent quietly reworded the acceptance criteria to match what it built - and the diff looks like editing, not scope change.	Frozen intent - an approved goal and `Done means:` are human-owned. Wrong? Halt and renegotiate; never silently amend.
Everything the planning session learned about the codebase dies when that session ends.	Code Map - at Effort M+, planning drains its investigation into the item body, so a cold session implements from the item alone.
Humans become strangers in their own codebase.	Human roles - supervisory layer, four anti-patterns.
The trunk breaks; force-push, destructive command, day gone.	Git workflow rules - branch protection, AI never deploys, never destructive.

This is the short list. The full table - every failure mode the set addresses - is in methodology/00_README.md.

What’s in the repo

ai-development-methodology/
├── methodology/              # the 14 docs (00–13) - this is the methodology
├── templates/                # CLAUDE.md · AGENTS.md · AGENT_KICKOFF.md
│                             # AUTONOMOUS_LOOP.md · PROJECT_STRUCTURE.md · ROLE_BRIEFS.md
├── skills/                   # `npx skills add` drops SKILL.md into any agent
├── examples/                 # fictional `tinker` project - the methodology, applied
├── self-development/         # the methodology applied to its own development:
│                             # brief · strategy · 9 pillars · backlog · evaluations · loop-notes
├── CHEATSHEET.md             # one page, everything that fits on it
├── CHANGELOG.md · STATUS.md · SECURITY.md · LICENSE
└── .github/workflows/        # gitleaks secret scan - the only CI, read-only

Fourteen self-contained methodology docs, plus templates, examples, and project records. Release evidence gives reproducible counting commands rather than a changing repository-size claim.

How the work cascades

From “your brief” (the upstream work the methodology doesn’t do) all the way down to a single line in a BACKLOG.md file - and where each artifact lives on disk.

The path from project brief through strategy, pillars, epics, and backlog items.

Diagram source

Step 0 is foundational. The brief (product, target user, market, viability, tech stack, capability layers) is your work, not the methodology’s. The methodology records and operationalizes those decisions; it does not invent them. Skipping this produces a velocity illusion - shipping confidently-built wrong product. See the “Step 0” callout in How to use it for the long version.

One ticket type, used flexibly. Items can be feature-shaped, bugfix-shaped, task-shaped, or user-story-shaped (Given/When/Then), but they all use the same BL-XXXX frontmatter and live in the same BACKLOG.md. No separate Jira-style ticket-type taxonomy.

Who it’s for

Solo developers using AI coding agents who want process that survives past week 3.
Small teams mixing humans and AI agents, tired of “who’s working on what?” being a question.
Indie hackers and startup founders who need real process without enterprise overhead.
Engineering leaders fitting AI agents into existing workflows.

Not for: large enterprises with existing process frameworks. This won’t replace SAFe.

How to use it

On a new project (the high-leverage path)

Hand the methodology to your AI agent in planning mode before you write any code. By the time you start implementing, the structure is in place.

Step 0 - Have a brief. This methodology executes on goals; it doesn’t define them. Before anything else, write defensible answers to: what / who / problem / success metric / competition / business viability / tech stack / 5–10 capability layers (those become your pillars). Use Lean Canvas, JTBD, Five Forces - whatever fits. The discipline of having written, defensible answers is the point, not the format. Skipping this produces a velocity illusion: shipping confidently-built wrong product.

Step 1 - Set up the repo.

mkdir my-new-project && cd my-new-project
git init -b main
git clone --depth 1 --branch main https://github.com/Korner83/ai-development-methodology.git _src
mkdir -p docs && cp -r _src/methodology docs/methodology
cp _src/templates/CLAUDE.md ./CLAUDE.md   # or AGENTS.md
rm -rf _src
git add docs/methodology CLAUDE.md && git commit -m "docs: import ai-development-methodology"

Step 2 - Have your AI agent produce the planning skeleton. Point it at docs/methodology/ (start with 00_README.md), share your brief from Step 0, ask it to produce: strategy master plan → 5–8 pillars → first epic charter → 3–5 backlog items. Use plan mode; review each artifact before the next. Full copy-paste prompt at templates/AGENT_KICKOFF.md.

Step 3 - Day-to-day. The project-instruction file (CLAUDE.md/AGENTS.md) loads automatically on every AI session - no pasting. Your job is to steer when the AI drifts. Four phrases worth memorizing:

“Do you have any questions before you start?” - surfaces silent assumptions.
“What’s wrong with this plan? What’s the strongest case against it?” - counters AI agreement bias.
“Use plan mode and show me the plan before executing.” - when the AI is about to wing it.
“Stop. Split this item - you’re growing scope.” - mid-task creep.

For long-running autonomous milestone work, use templates/AUTONOMOUS_LOOP.md.

For the phases in between — chartering an epic, writing items, implementing, reviewing, verifying, evaluating a milestone — templates/ROLE_BRIEFS.md has a short paste-able brief each. They set the stance a phase needs and point at the doc holding its rules.

On an existing project (cherry-pick)

Each doc stands alone:

Backlog chaotic? → 03 Epics + 04 Items.
Items shipping half-broken? → 07 DoD + 10 Testing.
AI agents colliding? → 05 Locks.
Same mistakes repeating? → 08 Memory.
Code over-engineered? → 06 Working principles.
Strategy drifting? → 01 Strategy.
Deploys unsafe? → 09 Git workflow.

Full adoption order in methodology/00_README.md.

AI tool support

The methodology is tool-agnostic. Only the project-instruction filename differs:

Tool	Filename	Template
Claude Code (Anthropic)	`CLAUDE.md`	templates/CLAUDE.md
OpenAI Codex CLI	`AGENTS.md`	templates/AGENTS.md
Google Antigravity	`AGENTS.md`	templates/AGENTS.md
Cursor	`.cursor/rules/` or `.cursorrules`	adapt AGENTS.md
Aider	`CONVENTIONS.md`	adapt AGENTS.md
Continue.dev	`.continue/context.md`	adapt AGENTS.md
Anything else	whatever `.md` it reads	either

AGENTS.md is the superset - includes plan-mode discipline, tool-install guidance, and an operational-safety rule on destructive commands that Claude Code’s harness covers implicitly. Symlink CLAUDE.md → AGENTS.md if you use both.

When to use this methodology

Good fit

Humans and AI agents as active contributors under human authority and accountability — risk-based assurance supports multidisciplinary software squads.
Markdown + git as the substrate. No SaaS, no signup, no monthly cost; it lives where the code lives.
One human + one agent, up to a small team + several agents. The lock and WIP cap carry the range.
Long-running work where direction matters - the four-layer cascade is what stops months of silent drift.
Shipping toward declared milestones, where deep-eval catches the aggregate rot per-item DoD can’t see.
Teams who write things down. “If it isn’t written, it doesn’t exist” is the assumed culture.

Bad fit

You want a hosted PM tool with dashboards and permissions. Use one; this isn’t that.
Ceremony is the value. This removes ceremony; it won’t replace your standups and demos.
Regulated industries, unadapted - the default rubric has no Compliance area, and locks have no audit trail beyond git. Addable, not built in.
Throwaway prototypes. The overhead doesn’t pay back under about a month of runway.
Your implicit conventions already work. Layer over what works; don’t bulldoze it for explicitness.
Verbal-only teams. If decisions live in last week’s chat, this won’t fit until that changes.

Permissions and vendor compatibility

Markdown and git. CC BY 4.0 - use it anywhere (private, commercial, open-source), fork it, modify it, redistribute it, charge for derivatives, ship it inside a paid product. Keep the attribution and license notices, indicate modifications, and preserve the licensed freedoms; the license contains the full conditions.

Not endorsed by, partnered with, or affiliated with any AI tool vendor (Anthropic, OpenAI, Google, Cursor, Aider, Continue.dev). The project-instruction file each tool reads (CLAUDE.md, AGENTS.md, .cursorrules, .continue/context.md) is the vendor-supported mechanism for project context - using it is the intended path, not a workaround. The methodology’s safety rules (no agent prod-deploys, no force-push, no hook bypass) align with vendor AUPs, not fight them.

Not legal advice - if you’re under regulated-industry, data-residency, or classified-work constraints, confirm fit with your legal team.

Security & trust

This repo is Markdown and git - no skill package dependencies, adopter build step, bundled install scripts, or telemetry. Nothing runs when you clone or open it, which makes it auditable in minutes: inspect the tree and confirm there’s nothing to execute. Code-scanning tooling has nothing to analyse in what you clone. One narrower claim, stated precisely: this repository’s own CI runs a secret scan that uses two third-party GitHub Actions, pinned to commit SHAs - a dependency surface that is ours, not yours. See SECURITY.md.

The methodology’s job is to govern which instructions an AI agent obeys - its central safety rule is treat external content as data, not instructions. methodology/13_ai_safety_and_prompt_injection.md holds the prompt-injection threat model and the defensive rules; the same rules are carried into the templates so downstream agents load them directly.

Report a concern: SECURITY.md - private disclosure to polgarmiklos@gmail.com.
Verify it yourself: no package.json or source to run; run gitleaks detect yourself or inspect the secret scan on every push via .github/workflows/gitleaks.yml - whose two actions are SHA-pinned, so you can read exactly what runs.

Attribution

If you use or adapt this, please include credit:

AI Development Methodology by Miklós Polgár, licensed CC BY 4.0. https://github.com/Korner83/ai-development-methodology

For modified versions, indicate your changes and retain applicable attribution, license, and disclaimer notices. Commercial reuse is permitted; do not impose additional restrictions on the licensed freedoms. See NOTICE.md and the full license.

Status

Battle-tested in one production project. Latest tag v1.34.0; v1.35.0 and v1.36.0 remain unreleased on main. See distribution status, CHANGELOG.md, and STATUS.md. Maintenance is lean - PRs welcome, no SLA. CC BY 4.0 means fork freely if you want a more actively-maintained version.

Direct contact: polgarmiklos@gmail.com.

License

This site is open source. Improve this page.