AI Can Write Code - But Can It Write Good Code?

Let's make it write good code.

It’s hard not to be amazed by the rapid advancements in AI coding agents. The potential they hold for speeding up development, handling boilerplate, and suggesting complex logic is almost unbelievable.

However, when you look closely at the code these AI tools produce, there’s an elephant in the room. Are we getting truly good code? Is it maintainable, understandable, and something we can confidently build upon for the long haul?

If left unguided, AI coding agents can generate lengthy, hard-to-follow functions, skip over important abstractions, and repeat itself unnecessarily. It gets the job done for the immediate task, but in doing so, it sometimes lays the groundwork for future headaches – what we often refer to as technical debt.

So, why does this happen? Why is there sometimes a gap between the code functioning correctly right now and being well-structured for the future? And, perhaps more importantly, how can we thoughtfully AI toward producing code that's not just functional but also elegant, robust, and sustainable? It likely requires understanding both the nature of these AI tools and exploring ways to work with them.

Understanding the Challenge: Where AI Needs Our Guidance

It seems like there are several factors contribute to this maintainability question:

• Learning Patterns vs. Understanding Principles: The LLMs driving these tools are incredibly adept at learning and replicating patterns from the vast sea of code they've been trained on. But this pattern matching doesn't necessarily equate to understanding the deeper software design principles – modularity, cohesion, separation of concerns – that experienced developers consciously apply. The AI might mimic both good and bad patterns without grasping the why behind them.

• The Nuance Lost in the Prompt: Often, we ask the AI what to do ("implement login") but our prompts naturally lack the rich, implicit context about how it should fit into our existing architecture, follow specific security practices, or adhere to our team's conventions. The AI does its best with the information given, and so it often defaults to the simplest or most common pattern it knows.

• Syntax vs. Semantic Depth: AI has become remarkably good at syntax – the grammar of code. The real challenge lies in semantics – the deeper meaning, logic, and architectural soundness. Maintainability is largely a semantic concern, requiring a level of understanding that's hard for AI to achieve just by predicting the next code token.

• The Temptation of the Quick Fix: Under pressure, it's easy to just add functionality in the most direct way, even if it complicates the codebase. Without a sense of long-term maintainability costs, AI might naturally gravitate towards these simpler, potentially messier, solutions.

Our Approach

Thinking about these challenges suggests that simply letting AI generate code freely might not be the most sustainable path. This is where a more structured approach to collaboration becomes really interesting. It views development not just as task delegation to AI, but as a genuine partnership with AI, where responsibilities shift based on who is best suited for each phase. Let's see how this might help address the quality gap:

• Requirements (Human Lead: ★★★ Human / ★☆☆ AI):

  • Thoughtful Start: The process intentionally begins with deep human involvement. We bring our understanding of the user, the context, and the strategic goals. By clearly defining the problem and scope upfront (perhaps starting in docs/design.md ), we lay a solid foundation, reducing the ambiguity that can lead AI astray. We focus on the user perspective and balance complexity versus impact.

• Flow Design (Balanced Lead: ★★☆ Human / ★★☆ AI):

  • Collaborative Architecture: Here, we work with the AI. We sketch the high-level architecture, perhaps leveraging established patterns like RAG or MapReduce, ensuring the overall structure makes sense before diving into code. The AI can then help refine the details within that thoughtful structure. We're essentially drawing the map together, as visualized perhaps in docs/design.md.

flowchart TD
    start[Start] --> process_input[Process Input]
    process_input --> core_logic[Core Logic]
    core_logic --> format_output[Format Output]
    format_output --> end[End]
    %% Conceptual Flow Example %%

• Utilities (Balanced Lead: ★★☆ Human / ★★☆ AI):

  • Building the Interface: We identify how our application needs to interact with the outside world (APIs, databases, file systems) – giving the AI its "body". While we define what's needed, the AI is a great partner in writing the code for these interfaces, ensuring they are robust and testable. A good example is a utility to wrap LLM calls, like the one suggested in utils/call_llm.py. It's important to remember core LLM tasks are not utilities, but part of the main flow logic.

# utils/call_llm.py structure (conceptual)
def call_llm(prompt):
    # Setup connection to LLM service
    # Send prompt, receive response
    # Return the meaningful content
    print(f"Simulating call_llm for: {prompt[:30]}...") # Placeholder
    return f"Response for {prompt[:30]}" # Placeholder

# Potentially include a test block
# if __name__ == "__main__": ...

• Node Design (AI Lead: ★☆☆ Human / ★★★ AI):

  • Detailing the Steps: Once the overall flow and tools are ready, the AI can take the lead in designing the detailed logic for each processing step (or Node in PocketFlow terms). This includes how data is read from and written to a shared state (which could be a simple dictionary or something more complex ), ensuring consistency. The design should cover the prep, exec, and post phases for each node.

    Python

# Conceptual shared state from cursorrules (4).txt
shared = {
    "input_data": { 
        # ... details ...
    },
    "intermediate_results": {},
    "final_output": None
}

• Implementation (AI Lead: ★☆☆ Human / ★★★ AI):

  • Focused Code Generation: With clear designs for each node, the AI can now generate the implementation code efficiently. Because it's working on smaller, well-defined units based on our earlier architectural work, the risk of monolithic or tangled code is reduced. It follows principles like "Keep it simple" and "Fail fast" initially. We see this stage reflected in the actual code files like nodes.py and flow.py.

# from utils.call_llm import call_llm # Assuming utility import

class ProcessDataNode(Node):
    def prep(self, shared):
        # Get data needed from 'shared'
        return shared.get("input_data", {})

    def exec(self, prepared_data):
        # Perform core logic using prepared_data
        # Important: Avoid accessing 'shared' here
        # result = call_llm(f"Process: {prepared_data}")
        result = {"processed": True, "details": "..."} # Placeholder
        return result

    def post(self, shared, prep_res, exec_res):
        # Update 'shared' with results
        shared["intermediate_results"] = exec_res
        # Decide next step
        return "default" # Or another action string

# from nodes import ProcessDataNode, AnotherNode # Assuming node imports

# process_node = ProcessDataNode()
# another_node = AnotherNode()

# Define flow connections
# process_node >> another_node 

# Create the Flow object, specifying the start node
# my_flow = Flow(start=process_node) 

• Optimization (Balanced Lead: ★★☆ Human / ★★☆ AI):

  • Refining Together: This is a crucial feedback loop. We review the AI's output, assess performance and quality using our judgment, and guide the AI in making refinements – maybe tweaking prompts, maybe suggesting code changes. It's an iterative process, potentially involving many cycles.

• Reliability (AI Lead: ★☆☆ Human / ★★★ AI):

  • Systematic Hardening: AI can systematically add tests, logging, and implement retry logic (perhaps using Node parameters like max_retries ) to make the application more robust.

So what’s next?

Our approach here doesn't suggest AI replaces human judgment; rather, it provides a structure to apply that judgment strategically. We believe that humans should lead strongly in the initial design and architecture, to guide AI towards generating code that fits within a sound structure.

Pocketflow’s workflow generator is built on delegating the right tasks to the right partner - be it the human or the AI. Moreover, our workflow framework has clear separation of concerns (like Nodes, Flows, and Utilities), which makes it easier to manage the distinct roles and handoffs between humans and AI.

We are actively working on the infrastructure to make sure that humans can BOTH retain control over code quality and leverage AI for implementation speed. If you have any feedback or thoughts - on improving training data with synthetic data, developing smarter algorithms, and creating better prompting techniques - please let us (helena@pocketflow.ai, jakobi@pocketflow.ai, or yosi@pocketflow.ai) know.