Agentic Development Discovery: Exploring the AGENTS.md Practice Model for AI-Assisted Development

Agentic Development Discovery, created by developer Damienb123, explores a new AI-assisted development model where large language models (LLMs) act as true collaborators rather than just code generators. The core innovation lies in two normative files—AGENTS.md and DESIGN.md—which serve as the "employee manual" and "design blueprint" for AI, enabling it to participate in the entire software development lifecycle from requirements analysis to testing. This project aims to shift the AI dev paradigm from snippet generation to full lifecycle collaboration.

Current AI tools like GitHub Copilot and ChatGPT have become daily companions for developers, but most remain at the "code snippet generation" level—developers ask, AI returns code, and developers copy-paste. While efficient, this mode doesn’t fully unleash AI’s potential. The vision of Agentic Development is to elevate AI from a tool to a collaborator that participates in all stages of software development, driving a paradigm shift in how humans and AI work together.

The project’s key methods are the AGENTS.md and DESIGN.md files:

• AGENTS.md: Acts as an onboarding guide for AI, defining role positioning (e.g., architect, developer), work norms (code style, branching strategy), tech stack details, communication protocols (when to ask questions vs. decide autonomously), and constraint conditions (performance, security).
• DESIGN.md: Focuses on architecture and design, including system architecture diagrams, core concepts, design decisions with tradeoffs, interface contracts (API specs, data formats), and evolution plans (technical debt, refactoring). These docs form the knowledge base for AI to understand the project context and deliver consistent, compliant outputs.

Unlike traditional imperative AI development ("write a function for X"), Agentic Development uses a dialogue-driven, iterative workflow:

1. Developer describes a high-level need (e.g., "add two-factor authentication").
2. AI first reviews AGENTS.md/DESIGN.md to grasp tech stack (e.g., Node.js + React), code style, and security requirements.
3. AI clarifies ambiguities (e.g., "TOTP or SMS? Backup codes?")
4. AI proposes a design (e.g., use speakeasy library, add DB fields, new API endpoints).
5. Developer gives feedback; AI adjusts the design iteratively.
6. AI implements incrementally (DB migration → backend API → frontend UI → tests), reporting progress at each step. This mirrors human-to-human collaboration: full communication, iterative design, and gradual implementation.

The project includes examples of AGENTS.md/DESIGN.md in action:

• Web app dev: From requirements to deployable full-stack app, using docs to align on tech stack and API design.
• Data pipeline: Generating ETL scripts and monitoring configs based on DESIGN.md’s data flow and error handling rules.
• CLI tool: Ensuring AI-generated tools follow Unix philosophy via AGENTS.md’s design guidelines.
• Automation testing: Creating comprehensive tests using DESIGN.md’s interface contracts. Each case shows how high-level needs translate to consistent, context-aware implementations.

Advantages:

• Context consistency: AI retains project norms via docs, avoiding "forgetting" constraints.
• Knowledge accumulation: Docs benefit both AI and human new members as project documentation.
• Reproducibility: Consistent outputs from the same docs.
• Progressive enhancement: AI "grows" as docs are updated with project evolution.

Challenges:

• Doc maintenance: Docs need constant updates to avoid outdated AI decisions.
• Initial investment: Preparing docs takes time, which may not be worth it for small projects.
• Normative boundary: Deciding what to include in docs requires practice.
• AI understanding: Models need strong long-text and multi-document correlation capabilities to use docs effectively.

Agentic Development doesn’t replace existing tools (Copilot, Cursor) but complements them—lower tools handle code details, while this framework manages context and norms. Short-term benefits: improved code quality, consistency, and onboarding efficiency. Mid-term: AI may make more autonomous decisions within normative boundaries. Long-term: AI-native development flows where humans focus on requirements and architecture, AI handles iterations.

In conclusion, Agentic Development redefines human-AI collaboration by emphasizing clear communication, norms, and feedback. Even if not fully adopted, thinking about how to help AI understand project context is a valuable step toward better AI-assisted development.