#3768 AI-Coding Assistant

#3768 Rather than trying to "code" AI agents in English, why not enter English design notes in source code, then have AI generate the real deterministic code to support the design?

That's an excellent and insightful question. You've essentially described the most powerful and practical way developers are beginning to use AI for coding. What you're proposing isn't an alternative to the current trend—it is the emerging best practice.

The short answer is: we are moving in that direction, and it's proving far more effective than trying to "code" entire applications with a single, massive English prompt.

This approach, often called Comment-Driven Development or AI-Assisted Scaffolding, is gaining traction for several key reasons.

## Why Your Idea is the Right Approach

Context is King: Placing design notes directly into the source code as comments provides the AI with immediate, relevant context. Instead of a generic prompt, the AI knows exactly which function, class, or module you're trying to build and how it fits into the larger project.
Developer-in-the-Loop: This method keeps the developer firmly in control of the architecture and logic. The developer defines the structure (the "what" and "why"), and the AI handles the tedious task of writing the implementation code (the "how"). This is a much safer and more maintainable workflow.
Built-in Documentation: Your design notes become the code's documentation from the very beginning. When another developer (or you, six months later) looks at the code, the intent is perfectly clear because it's written right above the implementation.
Iterative and Modular: You can build a complex system piece by piece. You write the notes for one function, generate it, test it, and then move on to the next. This is far more manageable than trying to generate an entire application at once, which often results in a "hallucinated" mess.

## How It Works in Practice (Today)

This workflow is already supported and encouraged by leading AI coding assistants.

Scaffolding a Function: A developer writes a function signature and a detailed comment or docstring describing its purpose, parameters, and return value.

# function: calculate_loan_payment
# parameters:
#   principal: the total loan amount (float)
#   annual_interest_rate: the yearly interest rate as a percentage (e.g., 5 for 5%)
#   years: the loan term in years (int)
# returns:
#   the calculated monthly payment (float)
# formula: M = P * [r(1+r)^n] / [(1+r)^n – 1] where r is monthly interest rate and n is total number of payments
def calculate_loan_payment(principal: float, annual_interest_rate: float, years: int) -> float:
    # AI generates the code here...

AI Code Generation: You then trigger an AI tool like GitHub Copilot or Cursor. It reads the comment and the function signature and generates the deterministic Python code to perform the calculation.
Review and Refine: The developer's job shifts from writing boilerplate code to reviewing, testing, and verifying the AI's output. This is a higher-value task that focuses on correctness and security.

## The Challenge: Why It's Not Yet a Silver Bullet

While this approach is powerful, it still faces challenges:

Ambiguity: English notes can still be misinterpreted by the AI. The developer needs to be precise in their descriptions.
Complexity Ceiling: It works exceptionally well for self-contained functions and classes. However, generating a complex, interconnected system with multiple dependencies still requires significant human architectural oversight.
Verification Overhead: You trade writing time for reviewing time. For very simple functions, it might be faster to just write the code yourself. The real benefit comes with more complex algorithms or boilerplate-heavy tasks.

In summary, your intuition is spot on. "Coding in English" is less about replacing programming languages and more about enhancing them. Using structured English design notes inside the code is the most effective way to guide AI to generate the robust, deterministic code we need. It's a partnership, not a replacement.

Seems like this could be incremental where the user provides the overall goal, the AI provides a framework, the user fills in details within the framework, and AI then generates the code for each user-selected function within the framework

Yes, absolutely. You've just outlined the ideal workflow for a human-AI software development team. This incremental, conversational process is the most effective way to leverage AI for complex projects.

This model, which can be thought of as iterative refinement, turns the development process into a structured dialogue between the architect (you) and the implementer (the AI).

## The Collaborative Development Loop

The workflow you described is a powerful loop that leverages the best of both human and machine intelligence:

Phase 1: High-Level Vision (Human-led) 🎯 You provide the overall goal. This isn't a detailed technical prompt but a clear statement of intent.
- You: "I want to build a web app for tracking personal fitness goals. It needs user accounts, a dashboard to log workouts, and a way to view progress charts."
Phase 2: Architectural Proposal (AI-led) 🏗️ The AI acts like a junior architect, proposing a standard, logical structure based on your vision. It generates a file tree, class shells, and empty function definitions with TODO comments.
- AI: "Okay, here is a project structure using a Python Flask backend and a simple HTML/CSS/JS frontend. I've created app.py, a templates/ folder with placeholder HTML files, and a static/ folder. The app.py has function stubs for login(), register(), log_workout(), and show_dashboard()."

Phase 3: Detailed Specification (Human-led) ✍️ This is where your expertise is crucial. You review the AI's framework, make architectural changes, and fill in the specific logic as detailed comments within the function stubs.

You (editing app.py):

# In the log_workout() function:
# 1. Get the workout type, duration, and calories from the form.
# 2. Validate that duration and calories are positive numbers.
# 3. Store the data in a SQLite database table called 'workouts'.
# 4. Redirect the user back to the dashboard.
def log_workout():
    # TODO: AI to generate code based on comments above
    pass

Phase 4: On-Demand Code Generation (AI-led) ⚙️ You select a specific function and instruct the AI to "fill this in." The AI reads your detailed notes and generates the precise, deterministic code to meet those requirements. You review, test, and repeat the process for the next function.

## Why This Model is Superior

Maintains Human Control: You remain the project architect. The AI suggests, but you decide. This prevents the AI from "hallucinating" a complex but unworkable solution.
Reduces Cognitive Load: Instead of trying to design and code an entire system at once, you focus on one small, well-defined piece at a time.
Perfectly Blends Strengths: It combines your strategic oversight and domain knowledge with the AI's ability to instantly write boilerplate and algorithmic code. It's the ultimate AI pair programmer 🤝.
Highly Agile: If you need to change a feature, you simply update the design notes in the relevant function and have the AI regenerate the code, making iteration incredibly fast.

Provide a formal process for doing this

Of course. Here is a formal process for this collaborative workflow, which we can call the Architect-Implementer Model (AIM).

This model treats the developer as the Architect who makes design decisions and the AI as the Implementer that handles code production. The process is cyclical, focusing on iterative refinement and constant verification.

## Phase 1: Conceptualization & Scoping

Objective: To define the project's high-level goals and constraints.
Primary Actor: Human Architect
Key Activities:
1. Define the Problem: Clearly state the purpose of the application and the problem it solves.
2. Outline Core Features: List the essential features required for a Minimum Viable Product (MVP).
3. Specify Constraints: Note any key technical requirements, such as the programming language, database, or deployment environment.
Deliverable: A concise Project Charter prompt. This is a well-defined paragraph that will be fed to the AI.

## Phase 2: Architectural Generation

Objective: To create a complete, but unimplemented, project structure.
Primary Actor: AI Implementer
Key Activities:
1. Process the Project Charter prompt.
2. Propose a suitable technology stack and design pattern (e.g., MVC, REST API).
3. Generate the project's directory structure, files, class shells, and function/method stubs.
Deliverable: An Architectural Skeleton. This is a runnable but non-functional codebase that serves as the blueprint for the project.

## Phase 3: Specification & Prioritization

Objective: To infuse the skeleton with precise human logic and to plan the implementation order.
Primary Actor: Human Architect
Key Activities:
1. Review and Refine: Modify the AI-generated structure as needed.
2. Annotate: Go into each function or method stub and write detailed, unambiguous comments describing the required inputs, outputs, and step-by-step logic. These are Specification Comments.
3. Prioritize: Identify the first logical sequence of functions to implement (e.g., user registration before user login).
Deliverable: An Annotated Skeleton with clear implementation instructions ready for the AI.

## Phase 4: Implementation Cycle (Iterative Loop)

This phase is a tight loop that is repeated for each function or component.

A. Code Generation
- Objective: To translate a single Specification Comment into functional code.
- Actor: AI Implementer
- Activity: Generate the code for one targeted function based on its Specification Comment.
- Deliverable: A single block of implemented code.
B. Verification
- Objective: To ensure the generated code is correct, secure, and efficient.
- Actor: Human Architect
- Activities:
  - Review: Read the code for logical errors or security flaws.
  - Test: Run the code, ideally with unit tests, to confirm it behaves exactly as specified.
  - Refine: Manually edit the code or rewrite the Specification Comment and have the AI regenerate it.
- Deliverable: A validated and tested code block.
C. Integration & Commit
- Objective: To merge the validated code into the main project.
- Actor: Human Architect
- Activity: Ensure the new code works with existing components and commit the changes to version control (e.g., Git).
- Deliverable: An updated and stable codebase.

## Phase 5: Deployment & Maintenance

Objective: To release and maintain the application.
Primary Actor: Human Architect
Key Activities: Once all core features from the Annotated Skeleton have been implemented and integrated through the Phase 4 loop, the application is deployed. New features or bug fixes are handled by re-entering the process at Phase 3 to create new Specification Comments.
Deliverable: A deployed application and a continuous maintenance plan.

From <https://gemini.google.com/app/> Google Gemini 2.5 Pro

Search This Blog

Learning from ChatGPT