Agentic Development Playbook: A Standardized Workflow for AI Programming

Agentic Development Playbook: Introduction to the Standard-Driven AI Programming Workflow

This project is maintained by manjast on GitHub (Original Link) and is a standard-driven workflow framework for AI programming agents (such as Claude Code, Cursor, etc.). Its core idea is AI-assisted programming requires discipline—it solves common issues like context loss, task drift, and code review difficulties through structured documents (e.g., decision logs, task lists), making the code repository the single source of truth.

Core Problem Background

Common issues in using AI programming agents include:

1. Decision Loss: Early decisions in long conversations are easily buried, forgetting the reasons for technical choices;
2. Task Disconnection: Traditional TODO lists become outdated, and task status is unclear when AI processes in parallel;
3. Difficult Code Review: AI generates large changes at once, making differences too big to review easily;
4. Lack of Evidence: Performance claims in ML projects lack reproducible evidence;
5. Template Sprawl: There are many outdated project templates, and new members don't know how to choose.

Solutions and Work Paths

Solutions to Core Problems

• Decision Loss: Use DECISIONS.md to append records of each decision (problem, solution, result, follow-up, date);
• Task Disconnection: TASKS.md with four-column structure (In Progress/Ready/Blocked/Completed) + STATUS.md to track status;
• Difficult Code Review: task-card.md clarifies task scope (In/Out of scope) + one task per commit;
• Lack of Evidence: GATES.ml-eval.md structured evaluation framework + run-manifest.json to record runtime metadata;
• Template Sprawl: Limit to 15 templates (13 user + 2 evaluation) and maintain via consistency checks.

Two Work Paths

• Core Path: Suitable for scenarios with clear standards, core documents include AGENTS.md, TASKS.md, etc., following rules like "repository as single source of truth" and "task atomization";
• PoC/Evaluation Path: Suitable for decision verification scenarios, with dedicated templates like POC-BRIEF.md, REPORT.md, etc., helping to clarify decision problems and keep summaries concise.

Consistency Check Mechanism

The project runs automated consistency checks via CI (completed in <5 seconds) to verify the following structural integrity:

1. Whether template fields are complete;
2. Whether run-manifest.json conforms to the reproducible format;
3. Whether GATES.ml-eval.md contains 7 required sub-checks.

This check only verifies structure, not content quality (content is reviewed by humans), ensuring documents comply with standards.

Practical Application Scenarios

Individual Developers

• Record decision history to avoid confusion like "why did I write this way back then";
• Clarify task boundaries to prevent AI from over-engineering;
• Transparent project status to keep track of progress at any time.

Team Collaboration

• Unify communication protocols to reduce context friction;
• Atomic tasks support asynchronous code review;
• Documented paths help new members get up to speed quickly.

ML Projects

• Structured experiment records and reproducible runtime environments;
• Clearly present decision evidence to ensure experiments are traceable.

Relationship with Other Tools

This Playbook is NOT:

• A requirement/specification generation system;
• A CLI or automation framework;
• A multi-agent orchestration product;
• A complete methodology covering all stages.

It is a tool-agnostic lightweight convention layer that can be used with any AI programming tools like Claude Code, Cursor, GitHub Copilot, etc.

Summary and Reflections

The Agentic Development Playbook marks the evolution of AI-assisted programming from "letting AI write code" to "standardized pair programming". The core insight is: Tools themselves cannot guarantee quality—discipline can.

Its value lies not only in providing templates but also in the way of thinking it advocates:

• Explicit and traceable decisions;
• Atomic and reviewable tasks;
• Ensuring quality through structural constraints rather than bureaucratic processes.

For teams and developers exploring best practices for AI programming, it is a well-thought-out starting point. Although not a silver bullet, it effectively solves real problems.