Spec Driven Develop and LLM Colaboration

sdd_process.md

graph TD
    subgraph "Phase 1: Specification & Design"
        A[Start: Project Idea] --> B{Spec Development w/ LLM};
        B -- "Iterative Refinement" --> B;
        B --> C[architecture.md];
        C --> D{Task Decomposition w/ LLM};
        D --> E[tasks.md];
    end

    subgraph "Phase 2: Implementation & Iteration"
        E --> F[Select Task];
        F --> G[Execute with AI Coding Assistant];
        G --> H{Code Review?};
        H -- "Yes (Every 3-4 Tasks)" --> I[AI Code Review];
        I --> J[Incorporate Feedback];
        J --> G;
        H -- "No" --> K[Commit to Version Control];
        K --> L{All Tasks Done?};
        L -- "No" --> F;
    end

    subgraph "Phase 3: Finalization & Review"
        L -- "Yes" --> M[Final AI Code Review];
        M --> N[Final Human Review & Linting];
        N --> O[Deployment];
    end

    G -- "Design Change Needed" --> C;

Loading

---

AI-Collaborative Development Framework

Overview

This document outlines a refined, spec-driven development process for building production-quality software in collaboration with AI agents. The methodology is founded on iterative loops, emphasizing detailed upfront planning and continuous feedback to guide AI agents effectively. This approach transforms the development lifecycle into a more efficient, predictable, and collaborative partnership between human developers and AI.

Core Principles

• Specification First: A well-defined architecture is the bedrock of the project. A significant portion of time should be dedicated to creating a clear and comprehensive specification before any implementation begins.
• Explicitness is Key: Communicate with AI agents as you would with a junior developer—with extreme clarity and no unstated assumptions. Define requirements, tech stacks, and expected behaviors precisely.
• Iterative Refinement: Treat all documents and code as living artifacts. Continuously improve specifications based on feedback discovered during implementation and review.
• Human-in-the-Loop: While AI automates repetitive tasks, human oversight is crucial for strategic decisions, architectural guidance, and final quality assurance.
• Frequent Integration: Regular commits and intermediate reviews act as safety nets, preventing divergence and ensuring the project stays on track.

Process Flow

Phase 1: Design & Decomposition

Objective: To produce a comprehensive architectural specification (architecture.md) and a granular task list (tasks.md) that will guide the entire development process.

Workflow:

1. Initial Specification Generation:

   • Partner with a high-level LLM (e.g., Qwen Coder, GLM 4.5, etc) to generate the initial architecture.md.
   • This document should explicitly detail:
     • Project Goals & Features: High-level objectives and specific user-facing functionalities.
     • Technology Stack: Specific versions of frameworks, libraries, and databases.
     • Data Models: Database schema definitions (e.g., DDL statements).
     • API Contracts: Endpoints, request/response formats, and authentication methods.
     • Project Structure: A clear file and directory layout.
     • Non-Functional Requirements: Guidelines on logging, error handling, and security.

2. Iterative Specification Refinement:

   • Engage in a "conversation" with the LLM to refine the architecture.md. The goal is to eliminate ambiguity.
   • A good rule of thumb is to allocate a significant portion of the total project time to this phase to prevent costly changes later.

3. Task Decomposition:

   • Once the architecture is stable, use an LLM to break it down into a sequential list of small, manageable, and testable tasks in tasks.md.
   • Review and adjust this list, ensuring that foundational tasks (e.g., setting up the database) come first.

Phase 2: Development & Review Cycles

Objective: To implement the solution by systematically working through the decomposed tasks, incorporating continuous feedback and integration.

Workflow:

1. Task Implementation:

   • For each task, provide an AI coding assistant (e.g., Roo code, Cline in an IDE or cli like qwen code, open code) with the full context of architecture.md and the specific task from tasks.md.
   • A standardized prompt is highly effective:

     "Please review the architecture.md document. Your task is to implement Task X from tasks.md. Propose a plan first. After I approve, write clean, minimal, and thoroughly tested code. Ensure all tests pass before considering the task complete."

2. Plan Review:

   • Always ask the agent for a plan before it writes code. This is a crucial step to catch potential over-engineering or misunderstandings early.

3. Version Control:

   • After each task is successfully implemented and tested, commit the changes to Git. Frequent commits provide a safety net and a clear history of progress.

4. Intermediate AI Code Reviews:

   • Every 3-4 tasks, conduct an AI-powered code review. This helps catch issues early and maintains code quality throughout the process.
   • Prompt:

     "You are a principal software engineer with a critical eye for detail. Review the code implemented for tasks 1-4. Ground your review in the architecture.md and focus on code quality, test coverage, and adherence to the specification."

5. Specification Upkeep:

   • If implementation reveals a necessary change in design, immediately update the architecture.md before proceeding. This ensures the specification remains the single source of truth.

Phase 3: Finalization and Deployment

Objective: To ensure the completed project is robust, compliant with the specification, and ready for deployment.

Workflow:

1. Final AI Review:

   • Once all tasks are complete, perform a comprehensive AI review of the entire codebase. This review should focus on holistic aspects like security vulnerabilities, overall architectural integrity, and final adherence to REST practices or other established standards.

2. Final Human Review:

   • A human developer should conduct the final review. This is the last opportunity to catch subtle logic errors, address linting issues, and ensure the project meets the highest quality standards.

3. Deployment:

   • With all reviews complete and issues addressed, the project is ready to be deployed through your standard CI/CD pipeline.

Recommended Tooling

• High-Level LLMs: Qwen Code, GLM 4.5, and so on.
• AI Coding Assistants: Cursor, an IDE with integrated AI capabilities.
• Knowledge Management: Obsidian, for its excellent linking and organization of markdown files.
• Version Control: Git.
• Terminal Management: tmux, for managing multiple processes like development servers and tests.

Future Vision: The AI Development Team

The ultimate goal is to evolve this framework into a fully automated system orchestrated by a primary agent:

1. A "manager" agent oversees the tasks.md file.
2. It dispatches individual tasks to specialized "developer" agents running in sandboxed environments (e.g., Docker containers).
3. Upon task completion, the developer agent submits a pull request.
4. A team of "reviewer" agents (specializing in security, architecture, and best practices) automatically reviews the PR.
5. Based on feedback, the PR is either merged or sent back for automated revisions.
6. A final human review gives the ultimate approval before triggering the CI/CD pipeline for deployment.