Why Does Your AI Development Workflow Need Design Docs?

A reliable ai development workflow starts with written design documents before any code is generated. Docs such as PRDs, ADRs, RFCs and engineering guidelines give the model the context it needs, cut hallucinations, and let tools like Cursor generate rules that constrain what the AI is allowed to do in your repository.

What Does an AI Development Workflow Look Like?

An ai development workflow has three phases: documentation, implementation, and review or bug fixing. The documentation phase defines what the software should do and why; the implementation phase turns that into code with AI assistance; the review phase covers code review and corrections in existing systems. Wesley Willians, from the Brazilian channel Full Cycle, presents this framework after reporting more than 1,000 hours of hands-on AI-assisted development, arguing that developers who skip the documentation phase see the model hallucinate and rewrite code irresponsibly.

The core argument is that documentation is an asset, the same way automated tests are an asset. A test written on day one still protects the project five years later; a design decision record written today still explains, years later, why a database, cache or library was chosen. With AI in the loop, that documentation does a second job: it gives the model the context it cannot infer from the repository alone.

The workflow also forces an honest scoping decision. Not every project needs every document. Willians explicitly warns against the idea that teams must produce thousands of documents; the point is knowing which document types exist and picking a blend that matches the project's size and purpose.

Which Design Docs Should Feed Your AI Development Workflow?

Six document families carry most of the weight in this workflow: product documentation, technical decision records, engineering guidelines, design and architecture documents, and operations and infrastructure documents. Each answers a different reader question, and each one feeds a different kind of context to the AI.

Product Documentation: PRD, TRD, FRD and User Stories

Product-side documentation describes what the software does. Four types matter most here:

• PRD (Product Requirements Document): the high-level definition of the project, its functional and non-functional requirements, and business and technology constraints.
• TRD (Technical Reference Document): specifies technically how the software communicates with other systems, including APIs, endpoints and contracts.
• FRD (Functional Requirements Document): details, at a lower level, how each module, feature or functionality behaves step by step.
• User stories: a narrative format, common in product teams, that explains when, how and where a capability is used, helping developers contextualize what will be built.

Developers can write these themselves to give the AI precise specifications, even when a product team owns them formally. Willians shows a generated context document containing an overview, the problem statement, objectives, expected outcomes, success indicators, in-scope and out-of-scope items, architecture, dependencies, constraints, risks and notes. For the AI, the success indicators are the definition of done: the model can check whether the software is actually working as intended.

Technical Decisions: RFC and ADR

Technical decision records answer a different question: why was this choice made? Two document types cover it. An RFC (Request for Comments) is common in open-source projects: the author writes justifications and a proposed design, circulates it for comments, and iterates until it approaches a final decision. In some teams an approved RFC itself is the decision; in others a second step formalizes it.

An ADR (Architecture Decision Record) is the lighter alternative: a short document that captures the context, the decision, its status (accepted, deprecated or superseded, with links to any replacement), positive consequences, and risks with mitigations. Willians's rule is blunt: if you do not know the downside of a decision, you are not ready to make it. In his demo, he generates an ADR for using Redis as a cache for a product catalog in a Go e-commerce, and the assistant confirms details iteratively, such as a 50-millisecond latency constraint and expectations of horizontal scaling, before producing the document.

Engineering Guidelines, Architecture and Operations Docs

Engineering guidelines define how the team works: code standards, good practices, basic security points, how code reviews are run, how tests are written, how pipelines and approval processes function, and how a pull request should be prepared. In companies with heavy compliance requirements, security gets its own category.

Design and architecture documents cover both ends of the zoom level. High-level system design documents show how components communicate, which Willians recommends especially for microservices or large ecosystems. Low-level documents describe componentization, sometimes down to classes, making internal boundaries clear to both the team and the AI. The C4 model, with its context, container, component and code levels, fits here; even though it is a visual notation, a model can read a C4 diagram expressed in code or text form.

Operations and infrastructure documents are the last family: how the CD pipeline works, how to run and restart the system, incident response procedures, and post-mortems. These matter when the AI is asked to help with operational work rather than feature code.

How Do You Generate Design Docs With AI Assistants?

The practical shortcut is purpose-built assistants. Willians shows custom assistants inside ChatGPT, such as a context generator that produces a PRD and an ADR generator, each driven by a prompt tuned for the document type. His broader point is that prompt design is a skill with many patterns: chained prompting, tree of thoughts, ReAct, and zero-shot, one-shot and few-shot prompting, each suited to a different use case. Documentation, implementation and bug fixing each deserve their own prompt.

The ADR generator works as a guided interview. It asks about the project, offers a detailed or a basic ADR template, proposes a title such as using Redis as cache for the product catalog, asks clarifying questions about read rates, scaling expectations and latency constraints, drafts the context, and confirms with the author before moving on. In the video demo, the whole exchange takes a few minutes.

The result is stored in the repository next to the code. Five years later, the team can still see why the decision was made, whether it is still in force, and which decision replaced it if it was superseded. That history is exactly what an AI assistant lacks when it is prompted cold.

How Do Cursor Rules Turn Documentation Into Guardrails?

Cursor, the AI-first code editor built on VS Code, has a feature called generate rules. You ask it to generate Cursor rules from the codebase, it reads the project's files, including the design documents, and writes rule files that describe how the AI should behave for each kind of implementation. In the demo, a rule generated from the rate-limiting ADR captures the choice of Redis, the Lua scripting approach for atomic operations, and concurrency guidance for the implementation.

This is the connection point between documentation and code generation: a document produces a rule, and the rule constrains what the AI may generate. Instead of the model improvising an architecture per prompt, it inherits decisions that were already reviewed and recorded. Willians notes that the generated rules are suggestions to review, not finished policy, but that the terms of the game become clear.

The same mechanism applies if the team uses GitHub Copilot in VS Code, JetBrains IDEs, or Claude or ChatGPT as assistants; the docs-first pattern is editor-agnostic. The repository rules are simply the most direct enforcement layer shown in the video.

What the Documentation Phase Does Not Solve

Documentation is only the first phase. Willians states plainly that generating rules and docs is not sufficient on its own: the implementation phase has its own workflow, and code review and bug fixing in existing systems each need their own process. The AI still makes mistakes after this setup, he says, but far fewer than when a developer asks it cold to implement a feature or improve code.

Two practical caveats follow from the demo itself. First, the AI-generated content, including the ADR and the Cursor rules, requires human review before being treated as authoritative. Second, the video's claim that hallucinations drop is the presenter's first-hand experience, not a measured benchmark; the framework reduces risk by improving context, and the size of that reduction depends on the project and the model used.

Frequently Asked Questions

• What is an ai development workflow? It is an organized process for building software with AI, divided into documentation, implementation, and review or bug fixing. Documentation gives the model context, implementation follows defined phases, and review catches what the model gets wrong.

• Do I need all these design documents in every project? No. The video explicitly says you do not need documentation for everything in every situation. Pick a blend of document types that matches your project's size and purpose.

• What is the difference between an RFC and an ADR? An RFC is a proposal circulated for comments before a technical decision is finalized; an ADR is a short record of a decision already made, including its context, status, benefits and risks. An approved RFC can itself serve as the decision in some teams.

• Can Cursor generate rules from my documentation? Yes. Cursor's generate rules feature reads the repository, including design docs, and writes rule files that guide how the AI should implement specific kinds of code. The generated rules should be reviewed before use.

• Does documentation reduce AI hallucinations? It improves the model's context, which in the presenter's experience reduces wrong or destructive output. This is reported experience rather than a measured benchmark, so treat the effect as project-dependent.

• Which AI tools does this workflow support? The video demonstrates ChatGPT for generating documents and Cursor for generating rules, but the docs-first pattern is editor-agnostic and works with GitHub Copilot, Claude, or any coding assistant that can read repository context.

• How long does it take to generate an ADR with an AI assistant? In the video demo, the guided interview produces a usable ADR draft in a few minutes, including clarifying questions about latency limits, scaling and read rates.

• Are C4 diagrams usable by AI coding assistants? Yes, when expressed in text or code form. The C4 model is visual, but a text representation of its context, container, component and code views can be read and reasoned over by a model.

• What comes after the documentation phase? The implementation phase, with its own phases and prompts, followed by AI-assisted code review and structured bug fixing for both new and existing software. Each phase has its own way of working.

From a Recorded Talk to a Reference Document

This article follows the same logic it describes: a talk full of decisions and context, captured in a form the reader can search, quote and revisit. If you have knowledge like this sitting in your own YouTube videos, whether tutorials, interviews or architecture walkthroughs, you can turn it into a written reference without rewriting it by hand.

Paste a YouTube URL into Skala Blog, get the transcription, and generate a structured article from it. The video becomes documentation; the documentation keeps working long after the recording.

Source video