Reviewed by Peter Lawrey on 24 August 2026.
Understanding what is needed, why it is needed, and what should not be built has never been more important.
Generative AI makes it possible to produce code and documentation faster than a team can honestly understand, review, and support it. Open Understanding is a workflow for optimising the complete path from an idea to validated production value, rather than merely optimising the speed at which artefacts are generated.
The primary production artefact is shared understanding. Code, specifications, tests, demonstrations, and review records are evidence that this understanding has been expressed accurately.
This public edition publishes the human-authored core principles and workflow, supported by deliberately compact public guidance. Executable demonstration projects are not included until they are ready for independent publication review.
Public advisory guidance is collected in the documentation map.
Each linked title opens related public advisory guidance and review questions. The principle statements here remain canonical.
- Understanding Is the Challenge
-
In my experience, before the use of generative AI, determining what needed to be written and why was about 95% of the time and effort. Editing the retained code and documentation was about 5%.
AI can compress work in the 95% through rapid exploration and increasingly selective rewrites. The final 5% does not necessarily shrink: a deliberate rewrite may take longer than mechanical reproduction because the author is using it to understand and take ownership of the retained result. Many use AI to focus on writing faster at the cost of understanding, which slows achieving value. This comes unstuck in honest review, or in support.
- Focus on Rationale
-
Documentation tends to describe what a program does. What is often lacking is why, and in particular why not something else. A decision log or Architecture Decision Record (ADR) can capture which choices were taken and what alternatives were considered but not taken. Maintenance needs this to make informed decisions about what can be changed and how. Maintenance often costs several times the cost of initial development.
- Code Review for Understanding and Support
-
Code review has two purposes: that the changes can be understood, and that at least two people understand them so they can be supported with some sense of ownership. AI has no ownership. If you have AI write and review code, no one owns it or cares if it works in the same way an owner does, or feels responsible when it fails.
- Different Metrics Tell Different Stories
-
During the first half of 2026, compared with my pre-AI practice, I estimate that AI produced ~20x the volume of content. Around 90% of the gross code produced was AI-written, but much of that code was disposable before the final cut. I retained around 2.0x the volume and personally wrote roughly 2x my pre-AI amount during the final rewrites, while business value increased by only about +20%. The value estimate is subjective, but informed by my visibility as CEO across both engineering delivery and business outcomes. AI makes it practical to attempt projects that previously were nice to have but too low value for the effort involved. In my experience, a significant proportion of AI-assisted functionality delivered is developer tools.
- Use File Format to Signal Status and Ownership
-
AI tools favour Markdown, whereas many developers favour AsciiDoc. I recommend using AsciiDoc for manually authored content to make its origin clear, and leave Markdown for AI working files.
- Narrow the Scope of LLMs to Increase Quality
-
The more functionality you can implement deterministically, the greater the quality, speed, and efficiency. Ideally once you have a stable implementation, you can get the LLM to help you write a rules-based classification program that doesn’t require an LLM when running, only for offline calibration. This is like distillation however the "model" has less than 1000 parameters.
- State Critical Intent in More Than One Form
-
While DRY (Don’t Repeat Yourself) is a good practice to start with, there are cases where writing everything multiple ways still has value. One of them is in prompt clarity. Write your goal, provide context, then write the goal again a different way. This leaves less room for ambiguity.
- Passing Tests Does Not Mean It Is Fit for Purpose
-
Beyond tests, you need a demo or acceptance project which is a more realistic use case. AIs work very well as mock users, as they have a repeatably cold understanding of what you are trying to do. They can help put together fairly rich use cases, for low effort. The fact they do things in ways you wouldn’t write can be useful for testing.
- Sometimes AI Tells You What Not to Say
-
Generative AI is an average of all its inputs, which is often better than nothing. If you are writing a README or introductory guide, or bootstrap content, AI can do a good job with some review and editing. However, if you are writing for an informed audience, you can assume that ~90% of what an AI produces your audience already knows. You should only be retaining the most compelling points, and what the AI doesn’t tell you.
- The Reverse Baltimore Phenomenon
-
AI tends to be good at filling an expected number of words but is often all at one elevation of what they are describing. In reality, you need the crucial details at all levels, very high to very low. The Baltimore problem is from cartography where Baltimore is near Washington meaning it doesn’t fit on small-scale maps, yet much smaller towns like Alice Springs appear to fill a space (the Reverse Baltimore Phenomenon).
- Human-Owned Content Should Let the Reader Reconstruct the Thinking
-
To help understand the purpose of your project, you should take the reader on a journey to follow your thinking process, not just the reasoning. This is something AI currently lacks.
- Define the Intent of the Project Upfront
-
Ensure everything ties back to the overall intent of the project. If the intent drifts too far, consider starting another project to keep each one focused.
- Use Specifications, but Do Not Trust Them Automatically
-
Specs will help improve your understanding and the quality of the code created, however especially for AI-written specs, most of it isn’t actionable, nor is the AI able to accurately say what is actionable. Initially it might not be worth even reading the specs. See Workflow Phase 1 & 2 below.
- For a Change, the Size That Matters Is Its Conceptual Load
-
It’s easy to measure the number of lines of content altered, yet this is a poor indicator of the effort required to review and understand it. We can update the year in all our copyright messages, touching 10K files without much conceptual load. However, changing one line in a critical section of code probably requires much more consideration.
I suggest working in phases, each moving from rapid development to higher quality. In simple cases some of these steps can be dropped. You might stop without completing all of these phases either because you don’t need a higher level of quality, or it’s not working out as you need, i.e. the idea wasn’t as good as you thought. Either way this can save you a lot of time and effort compared with attempting a high production grade of quality from the start.
Each linked phase opens public advisory guidance that expands the workflow without changing the phase definitions here.
This workflow is largely top-down. Before starting each of Phases 1 to 4, consider which bottom-up design changes, fixes, or implementation work are worth completing first. Resolving them can simplify the next phase and focus it on what remains to be added.
Before formalising the requirements, it can be well worth your time researching what other ideas are publicly available. This could save you a lot of time later.
In this phase I favour ChatGPT Web App as I find it more likely to reference other websites and to search the internet more broadly. Gemini and claude.ai are likely to do as good a job, but I am more familiar with ChatGPT.
Once I am happy with that I ask it to create a download pack.
At every stage, I suggest using multiple AI models to critically review the progress before you review the content. For non-trivial projects, ask the AI to make quick fixes or add specs and/or tasks to be implemented to address issues found. To encourage high-level versus low-level detail examination, I will start by asking for 25+ findings from each agent, then ask for 50+, then 100+, perhaps 200+ for a bigger project. This will encourage increasingly pedantic issues to be found.
Using the download pack, I can ask Codex to build a project or add to an existing one. I can prompt Codex to ask 50 questions for the planner to answer to broaden the research.
The goal of this phase is to create a vibe-coded implementation which is mostly complete, though the quality might be barely enough to be able to determine this.
It is likely that many revisions and extra ideas will be added resulting in a messy spec and implementation. A good portion of the suggested specs aren’t actionable; however, the only way to know this is to try and see.
Using Codex, and Claude Code, you can ask it to provide recommended additional specs/requirements and implement those. In one case, a project that started with 100 specs in Phase 0 ended up with 650 in Phase 1.
This approach is more in line with vibe coding where there is a tight ad hoc evaluate, update specs, implement loop.
|
Note
|
At this stage I have only looked at what is produced, but not read the specs or code in any detail. |
By using the first phase and its more-or-less working reference implementation as a starting point, you can ask the AI to rewrite the specs based on lessons learnt.
This produces a much more coherent and concise specification based on what the AI could actually implement in Phase 1.
Next you ask it to rewrite the implementation, drawing on the specs and the previous implementation if needed.
Across about three projects so far, I have typically seen the Phase 2 rewrite reduce the specification volume by a factor of around five. This is not merely editorial compression: after attempting a reference implementation, both the AI’s and my view of what actually needs to be specified have changed substantially through learning by doing. In the project mentioned above, the rewritten implementation also contained about half the code.
This approach is more in line with sprint development where specs are implemented in a planned manner in batches for efficiency.
Before attempting a rewrite in Phase 4, the gap between what the AI produced and how you would write it might be too big a step.
In this phase you want to refactor the large portions of code/content, e.g. classes and files added, so it’s much closer to how you would have named things, laid it out, and structured your changes.
The goal is to be comfortable that a rewrite could be done in isolation. This requires reading all the release code produced, but only to check that it’s at least close to what you would want.
Much of the non-release code can also be reworked in this stage.
The goal of this phase is to produce code that you feel is what you would have written. You should only include what you understand, and consider dropping for another project anything you don’t. Up to this point, you haven’t put that much effort into it, so you should feel that unless it’s compelling to keep, park it for later or delete it.
The quality of the documentation and tests is more of a judgement call. Release code will be used in production. I take the view that the tests should be realistic demos of how the software could be used, and you should expect users to copy this behaviour.
This approach is more in line with waterfall, where you have a complete spec and reference implementation, before writing a release-quality version.
Before merge, an independent reviewer should be able to explain in their own words the intended business or user outcome, the observed behaviour that changes, what deliberately remains unchanged, and how this will be communicated to the affected users.
These cross-cutting resources connect the principles and workflow to established practice and practical adoption:
Open Understanding seeks to make that value, the reasoning behind it, and the responsibility for supporting it visible throughout the path from idea to production.
This public edition is licensed under the Apache License, Version 2.0. Review feedback and small documentation corrections are welcome during the public preview. See CONTRIBUTING.md before submitting material.
Open Understanding is advisory guidance. It does not replace legal, contractual, security, safety, accessibility, or sector-specific obligations. AI capabilities and failure modes change; responsibility for a maintained system remains with the people and organisations that choose to build, release, and operate it.