| 🌐 English | 🌐 日本語 |
AI-assisted coding is not defined by how accurately AI writes code on the first attempt.
Its true productivity comes from how reliably AI can correct its own mistakes (Fixability).
And what determines this correction capability is
the quantity and clarity of information AI needs to correctly understand the context (Semantic Transparency).
This framework is designed to systematically explain the stability of AI code generation
through the two axes of “Fixability × Semantic Transparency”.
As a technical consultant and developer using AI coding agents in practice, I’ve observed the following challenges:
This explanatory model emerged from a desire to make this problem structurally explainable.
It’s not “AI makes mistakes because it’s immature”
but rather “AI lacks sufficient information to make correct judgments”
With this perspective, instead of relying on personal intuition or magic prompts,
you can explain what information was provided to AI that led to this result
as a deficiency in context design.
This site introduces an overview of the following components:
What matters in AI code generation is not “getting code right on the first try”
but rather “whether it can be correctly fixed when wrong”.
The more stable the correction loop converges, the better AI’s output quality and work speed.
For AI to correct properly, it needs materials to understand the situation:
The more complete these are, the less AI misreasons, and the more stable the correction loop.
These two are not independent but strongly interconnected:
In other words, Fixability is not just about AI’s capability—Semantic Transparency is a human-side information design problem.
Systematically identify points where AI is likely to misreason for each project.
Input:
Output:
When you input your project’s language, version, libraries, and runtime environment,
a model-agnostic diagnostic prompt automatically identifies
points where AI is likely to misreason and provides countermeasures.
Explore the theoretical background and thought process of the framework.
Detailed documentation, diagnostic prompts, and samples
are published in the GitHub repository.
| Point | Explanation |
|---|---|
| Challenge | AI code generation instability stems not from “AI immaturity” but from missing contextual information |
| Key | Stability of correction loops (Fixability) |
| Solution | Enhance semantic transparency (Semantic Transparency) |
| Diagnosis | Proactively identify project-specific risks with 9-axis diagnostic prompt |
By focusing not on “how to use AI” but on “information misalignment between AI and humans”,
you can stably improve AI coding productivity and quality.
With the emergence of AI coding agents, an era where AI generates code has arrived.
However, cases are increasing where AI-generated code doesn’t match project context,
or even when error information is provided, corrections spiral into a quagmire.
Common responses to this situation:
However, as long as you rely on “personal intuition (gut feeling)” and “prompt magic (luck)”, project productivity remains hit-or-miss and doesn’t scale.
This framework’s perspective:
Rather than demanding perfection from AI,
place “information opacity between AI and humans” under engineering control
Definition of Misreasoning (Mis-inference):
Not errors in the model’s learning process, but errors in context selection during the inference phase.
In other words, the phenomenon where AI selects knowledge unsuitable for the project’s context during reasoning.
This perspective enables you to explain
“what information was provided to AI that led to this result”
not through personal intuition but structurally.
AI-prone misreasoning areas are classified into the following 9 evaluation axes.
(The 9 axes are intentionally not independent—they’re structured to influence each other.)
Community Consistency
Variations in community practices that cause AI to misselect context
Example: Confusion between .NET and .NET Framework, ASP.NET MVC vs Minimal APIs factions
Documentation Consistency
Inconsistencies between official and unofficial documentation that mislead AI’s knowledge reference
Example: Old API documentation versions, deprecated writing styles in blog posts
Practice Consistency
Fluctuations in practice (writing styles, conventions, structure) that confuse AI code generation
Example: Differences in database migration procedures, variations in naming conventions
Dependency Stability
Update frequency and breaking changes in dependent libraries that destabilize AI reasoning
Example: Node.js major version upgrades, Python package compatibility breaks
API Consistency
Lack of API consistency that induces AI’s incorrect invocations
Example: Same functionality implemented in multiple ways, different parameter orders
Ecosystem Consistency
Differences between frameworks and toolchains that confuse AI reasoning
Example: Build tool choices (Maven/Gradle), test framework options (Jest/Vitest)
Static Semantic Service
Richness and consistency of semantics AI can reference at compile time
Example: Type systems, AST, static analysis APIs (Roslyn, tsserver, etc.)
Runtime Semantic Service
Stability and determinism of semantics observable at runtime
Example: Exceptions, dynamic types, presence/absence of runtime type information
Core Semantic Consistency
Consistency of the language specification itself
Example: Semantic fluctuations due to historical context, backward compatibility policies, cultural values
Misreasoning Points in Community Consistency:
Countermeasures to Provide AI:
Misreasoning Points in Community Consistency:
Countermeasures to Provide AI:
Key Insight:
The more detailed project-specific context you provide, the more detailed the diagnosis and the more practical the countermeasures.
Why this framework is powerful:
A framework developed to systematically explain AI coding stability
from the perspectives of technology, language specifications, AI models, and project structure.
Author: Masaki Honda
(Technical consultant, 40+ years of programming experience since MS-DOS era)
License: MIT License
Free to use, modify, and distribute. See LICENSE for details.
Initial public release: 2025/12/29
This framework is published as a thought experiment, and empirical validation is ongoing.
Community extensions and improvements are welcome.