Why AI coding agents fail with incomplete specs

GitHub logo

AI coding agents like Codex and Claude Code are getting surprisingly good at writing code.

But after using them in real projects, I noticed something:

Most failures were not caused by the model.

They were caused by incomplete specs.

When a specification has gaps, the AI fills them in with plausible assumptions. At first the generated code often looks correct, but over time the implementation slowly drifts away from the intended behavior.

I kept running into issues like:

  • missing auth boundaries
  • unclear tenant ownership rules
  • retry and race-condition problems
  • webhook duplication edge cases
  • requirements enforced only on the client side
  • implementation drift between spec and actual behavior

Eventually it becomes difficult to tell whether the bug is:

  • in the implementation,
  • in the specification,
  • or in the original requirement itself.

A Real Failure Case

One issue I repeatedly saw was missing tenant ownership validation.

A spec would describe:

  • authentication
  • API structure
  • expected responses

but never explicitly define ownership constraints.

The AI agent would generate code that correctly authenticated the user, but still allowed cross-tenant access because ownership validation was never part of the specification.

The implementation looked reasonable at first glance.

But the security boundary itself was undefined.

That was the moment I realized the problem was often not “bad code generation.”

It was ambiguous requirements.

The Idea

I started building an open-source tool called SpecGuard.

The goal is simple:

Review requirements before they become input to an AI coding agent.

Instead of reviewing generated code after implementation, SpecGuard tries to catch ambiguous or incomplete requirements earlier in the workflow.

This is heavily inspired by problems I encountered while experimenting with:

  • AI-assisted development
  • LLM coding agents
  • spec-driven development workflows

Intended Workflow

Write spec
    ↓
Run SpecGuard
    ↓
Fix NOT_READY findings
    ↓
Hand spec to AI coding agent

What SpecGuard Checks

Main validation areas

SpecGuard mainly looks for ambiguous or missing areas such as:

  • auth and permission boundaries
  • tenant ownership rules
  • idempotency and replay safety
  • race conditions
  • expiration and revocation handling
  • state transitions
  • webhook/background retry behavior
  • requirements relying only on client-side validation

The output is one of:

  • READY
  • READY_WITH_WARNINGS
  • NOT_READY

Why the Default Mode Does Not Use an LLM

I intentionally made the default path non-LLM.

I wanted spec validation to behave more like linting:

  • deterministic
  • reproducible
  • CI-friendly
  • cheap to run repeatedly

LLM-based review exists as an optional deeper layer, not the foundation.

There is also an optional OpenAI/Codex-based deeper review mode, but currently I treat that as a secondary layer rather than the default workflow.

Codex Plugin

In v0.4.0 I added an MVP Codex plugin.

Install:

pip install spec-guard
specguard --help

codex plugin marketplace add KoreaNirsa/spec-guard --ref main

Create an example spec package:

specguard example copy specs/your-feature-name --force

Inside Codex, the plugin can:

  • run SpecGuard analysis
  • read generated results
  • summarize READY/NOT_READY state
  • explain main findings and next actions

The plugin itself does not reimplement the engine.

It wraps the existing CLI workflow.

GitHub PR Review Workflow

SpecGuard also includes a GitHub Actions-based PR review workflow.

When a spec package changes in a PR, it can automatically run SpecGuard Review and leave findings directly on the PR.

The OpenAI review path currently uses GitHub secrets such as:

SPECGUARD_OPENAI_API_KEY
SPECGUARD_PR_REVIEW_MODEL
SPECGUARD_REVIEW_SPEC_PATHS

Current Status

This project is still very early and pre-beta.

I do not expect it to perfectly judge every specification.

Right now I am mainly interested in feedback around:

  • what kinds of specs this workflow fits well
  • where deterministic checks break down
  • which findings feel too noisy or too weak
  • whether PR enforcement would fit real engineering workflows

If you are already using AI coding agents in production workflows, I’d genuinely like to know:

  • what kinds of spec failures you see most often
  • where deterministic validation breaks down
  • and whether something like this would actually fit your development workflow

I’m especially interested in situations where the generated implementation looked correct, but the requirement itself was underspecified.

Feedback, issues, and PRs are all welcome.

GitHub logo

KoreaNirsa
/
spec-guard

Validation-First Workflow (VFW) for AI-assisted development

SpecGuard banner

SpecGuard

SpecGuard blocks weak specs before AI coding agents turn them into defective code.

SpecGuard is a Validation-First Workflow (VFW) for AI-assisted development
It turns specs into reviewed, testable, implementation-ready packages before AI coding begins.

It is not a prompt-to-code generator. SpecGuard helps you prepare an approved spec package before an external Codex, Claude Code, or another coding agent writes application code.

Demo Video

SpecGuard demo walkthrough

Watch the full-resolution MP4 demo

The demo follows this flow:

  1. Install SpecGuard with pip install spec-guard.
  2. Copy the example spec with specguard example copy your-feature-name --force.
  3. Insert a vulnerable spec. In v0.3.0, the packaged example intentionally includes a vulnerable spec by default so users can see a blocking SpecGuard Review.
  4. Review the SpecGuard findings.
  5. Fix the weak areas directly, or ask an AI assistant to strengthen the spec by giving it the SpecGuard Review findings.
  6. Run SpecGuard Review again and confirm it reaches READY…

Yalova Üniversitesi'nde 7 Ayda İlk Tekne Üretildi: Hedef İnsansız Deniz Aracı

Yalova Üniversitesi Çınarcık Meslek Yüksekokulu’nda Türkiye’de ilk olan Fiber Tekne İmalatı ve Kompozit Kalıp Programı öğrencileri, 7 ayda ilk teknelerini üretti. Rektör Prof. Dr. Mehmet Bahçekapılı, bölümün istihdam odaklı ve Yalova’nın denizcilik kültürüyle uyumlu olduğunu belirtirken, okul müdürü Dr. Öğr. Üyesi İzzet İsmail Dur ise 2027-2028 yılında insansız deniz aracı üretmeyi hedeflediklerini açıkladı.

HAYAT Finans ilk çeyrekte 35 milyon lira net kar elde etti

HAYAT Finans, yılın ilk çeyreğinde aktiflerini yüzde 33 artırarak 33,6 milyar liraya, kredilerini yüzde 39 büyüterek 19,2 milyar liraya yükseltti. Net karı 35 milyon lira olan banka, dijital bankacılık ve yapay zeka yatırımlarına devam edecek.

Dijital Şiddet Empati Yeteneğini Yok Ediyor

Gaziantep Üniversitesi’nden Doç. Dr. Süleyman Şahin, dijital mecralarda şiddet içeriklerine maruz kalan çocuk ve gençlerin duyarsızlaştığını, empati yeteneğini yitirdiğini belirtti. Şahin, siber zorbalık ve uygunsuz içeriklerin risk oluşturduğunu, ebeveynlerin dijital ebeveynlik yapması ve medya okuryazarlığı dersinin zorunlu hale getirilmesi gerektiğini vurguladı. Tamamen yasaklamak yerine rehber olmanın önemine dikkat çekti.

Quiet Exits, Quiet Collapse (Part 1): How People Become Exitable without Noise

Technical professional presenting concerns during a corporate meeting while colleagues quietly disengage and continue the process without responding.

There is a specific kind of professional experience that has no official name.

It is not termination. It is not conflict. It is not the moment someone decides to leave.

It is the period before any of those things — the weeks or months during which a system a person is still formally part of begins quietly processing them as a problem rather than a contributor. Credentials remain intact. The analysis remains accurate. The role still exists on the organizational chart. But something shifts in how the organization receives the individual, and the change becomes perceptible long before it becomes explainable.

Most people who have experienced this describe it similarly: a gradual cooling. Responses slow. Rooms feel slightly different upon entry. Conversations that previously included them begin completing themselves before they arrive. Nothing explicit is said because nothing explicit needs to be said.

The system has already made a determination.

What follows is not conflict.

It is the administrative processing of an exit that has already been decided.

This episode is about that process — how it functions, how it conceals itself, and why it leaves almost no recoverable artifact once complete.

What follows is not organizational theory.

It is a documented sequence.

ACT 1 — The Reclassification

There is a point where it no longer matters whether someone is right.

Not a visible threshold. Not a formal meeting. Not a moment recorded inside any system of governance. The shift occurs in reception, not in content. The analysis remains intact. The data remains consistent. What changes is how the organization processes the source of that data.

Signals that previously triggered engagement begin producing no operational response. Contributions stop generating disagreement and begin generating silence. Questions are no longer pursued. The absence of friction is not alignment.

It is non-recognition.

A structural transition has occurred, and it is precise:

the individual is no longer processed as an input into decision-making.

They are processed as a condition requiring management.

This transition does not require new evidence. It is not based on measurable performance deterioration. It requires only one determination:

continued engagement with this person’s signals now produces more organizational cost than continued disengagement.

Once that determination is made, the interpretive framework reverses.

Behaviors previously categorized as rigorous become recategorized as obstructive. Precision becomes inflexibility. Persistence becomes misalignment. Past contributions are quietly re-indexed under the new interpretation without formal revision, notification, or appeal.

The system does not update its assessment.

It replaces it.

And it does so retroactively — so that the new interpretation appears not as a reaction to recent events, but as a delayed recognition of a pattern that was supposedly always present.

The room does not become hostile.

It becomes quieter.

Technical professional presenting concerns during a corporate meeting while colleagues quietly disengage and continue the process without responding.The data remained. The reception changed. (Gemini generated image)

ACT 2 — The Quiet Targeting

Once reclassification has occurred, the system does not initiate confrontation.

It initiates omission.

The individual remains present across formal structures. Meetings are attended. Contributions are delivered on schedule. The procedural surface is maintained with complete regularity.

What changes is processing.

Contributions are not rejected. They are not debated. They are not integrated. They are bypassed — absorbed into the formal record and left there, undisturbed and without consequence.

The behavioral signature is consistent:

the individual speaks into the system, and the system no longer routes the signal anywhere meaningful.

Presence is maintained.

Influence is revoked.

The distinction between the two is never formally acknowledged.

When concerns emerge that resist reframing — compliance deviations, quality gaps, structural inconsistencies — the response no longer addresses the content.

The response shifts to the container.

Timing is questioned. Tone is noted. Communication channels are redirected. The “appropriate forum” is identified as somewhere other than the current discussion.

The issue becomes the manner of delivery.

The signal becomes the problem.

This process is rarely experienced internally as suppression. Most participants continue interpreting themselves as constructive actors preserving coordination and reducing friction.

The mechanism operates through distributed reinterpretation rather than explicit instruction.

The targeting proceeds quietly because, from inside the system, it does not feel like targeting.

It feels like adaptation.

Corporate communication network visually routing around an isolated employee who remains physically present in the organization.Still inside the system. No longer inside the flow. (Gemini generated image)

ACT 3 — The Social Topology Shift

Following targeting, a second process activates — one operating not vertically through hierarchy, but laterally through the informal network the individual depends on to function.

The system does not need to remove them.

It only needs to make association with them expensive.

This cost adjustment propagates without directive and without coordination. No memo circulates. No explicit instruction is issued. What circulates instead is context — a shared understanding of where this person now sits inside the organization’s invisible risk structure, and what visible alignment with them may now imply.

Peers do not necessarily revise their private assessment of the underlying concern. A colleague who knows the quality issue is legitimate does not suddenly believe it is illegitimate.

What changes is observable behavior.

And the determining variable is not conviction.

It is exposure.

A peer who previously copied someone on preparatory materials begins doing so slightly later, then inconsistently, then not at all. Direct communication becomes intermediated communication. Prior visible alignment quietly migrates off the record.

None of these changes are individually significant.

Each is locally explainable:

  • calendar pressure
  • administrative variation
  • evolving workflows
  • communication oversight

Together, they produce a social topology in which the individual remains formally connected to the network while their signal no longer reaches the nodes where decisions are actually made.

The aggregate effect is coordinated without centralization.

Everyone makes a local decision.

The local decisions produce a collective outcome that no single person designed and no single person needs to acknowledge.

Employee walking through a corporate office where colleagues subtly disengage and visible alignment has quietly disappeared.Association became expensive. (Gemini generated image)

Docket 8.1 — The Invisible Participant

A quality engineer continues attending program reviews following a formal compliance escalation. Contributions are delivered within expected process parameters, documented, and fully consistent with the engineer’s defined responsibilities.

No response is directed toward the substance of the raised concerns. Agenda progression continues. The meeting concludes. The concerns remain formally on record and operationally untouched.

The engineer remains included across all official distribution structures. Over time, preparatory materials begin arriving inconsistently — partially, late, or not at all. When noted, the gaps are attributed to administrative variation. No corrective action restores the prior information flow.

Formal inclusion persists.

Functional participation has ceased.

No document captures the transition between those two states. No record marks the date on which one became the other. From an audit perspective, the individual remained a fully participating member of the organization throughout.

From an operational perspective, they had already been removed.

Quality engineer presenting compliance concerns during a program review while the organization procedurally continues without responding.Formal inclusion. Functional invisibility. (Gemini generated image)

ACT 4 — The Paper Trail

Once isolation stabilizes, the system begins aligning its formal artifacts with the informal conclusion it has already reached.

The sequence is inverted relative to standard accountability models.

The decision precedes the documentation.

This phase is the mechanism most likely to be misunderstood externally and most immediately recognized by those who have experienced it directly.

The documentation accumulating during this phase does not record deterioration. It does not capture a meaningful change in conduct or capability.

It constructs a retrospective narrative that makes a predetermined outcome appear to be the natural conclusion of an objective process.

Behavioral markers follow a recognizable pattern.

Feedback previously delivered informally and positively begins appearing in written form with altered framing. Generalized concerns regarding alignment, communication style, and cultural fit begin surfacing in language lacking specific behavioral referents — no incident, no defined threshold, no corrective sequence preceding the concern.

Documentation density increases without corresponding behavioral change.

The formal record is being constructed.

Not to capture what happened.

To make what was decided defensible.

Docket 8.2 — The Risk Designation

A supervisor verbally designates a team member as “a failure and a risk” during a direct exchange. No criteria are provided. No prior documentation supports the designation. No formal process has been initiated that would give the classification procedural standing.

The individual’s observable work output remains unchanged. Professional conduct remains unchanged. What has changed is compatibility with the organization’s current stability requirements — specifically, continued insistence on surfacing a compliance issue the system has determined should not continue surfacing.

In the weeks following the exchange, written documentation begins accumulating. The documentation references generalized concerns regarding behavior, alignment, and team impact. The language implies an existing pattern. It does not reference the compliance escalation itself.

The paper trail does not record what happened.

It records what the system needs to have happened.

From an external review perspective, the record appears coherent and procedurally grounded. From inside the actual timeline, the documentation emerged after the conclusion — assembled in support of an exit already determined during a verbal exchange that left no artifact at all.

The designation was positional, not behavioral.

It was therefore not correctable.

The individual could not continue surfacing the compliance issue without deepening the designation, and could not challenge the designation without abandoning the compliance issue itself.

The system had closed both paths simultaneously.

Closing — Before the Exit

By the end of this sequence, the formal exit has not yet occurred.

The individual is still present. Still attending meetings. Still producing work meeting professional standards. Still, in every visible sense, a functioning member of the organization.

But the removal is already complete in every sense that matters.

Impact has been revoked. Influence has been withdrawn. The social network has redistributed its visible alignment. The paper trail has been constructed.

The organization has already adapted to the absence of this person’s corrective capacity.

What comes next is administrative.

The system will eventually close the file.

But the decision was made long before the file existed.

Episode 8, Part 2 — The Quiet Collapse
What the system loses when the exit completes — and why it cannot measure the loss.

🔎 The Corporate Breakdown Files — Full Series Overview

  • Prologue — Power Without Accountability: How Modern Corporations Create Their Own Failures
  • Prequel — The Blind Spot: Why Companies Collapse While Leaders Celebrate
  • Episode 1 — The Incentive Collapse: When KPIs Turn Leaders into Saboteurs
  • Episode 2 — The Silence Weapon: When bad news stops flowing upward
  • Episode 3 — The Process Illusion: When documentation replaces decisions
  • Episode 4 — Deniability Engineering: How Leaders Delegate Blame but Centralize Power
  • Episode 5 — The Metrics Mirage
  • Episode 6 — Narrative Control
  • Episode 7 — The Gatekeeper Class
  • Episode 8 — Quiet Exits, Quiet Collapse
  • Episode 9 — The Conflict Vacuum
  • Episode 10 — Silo Warfare
  • Episode 11 — The Snap Moment
  • Episode 12 — Rebirth or Rot
  • Episode 13 — Scapegoat Economics

👉 New episodes released as the real-world case evolves.

🔖 Follow this series for real-world patterns of corporate dysfunction — and how to survive them.

© 2026 Abdul Osman. All rights reserved. You are welcome to share the link to this article on social media or other platforms. However, reproducing the full text or republishing it elsewhere without permission is prohibited.