Requirements definition in the era of AI agents: A three-layer design (Spec, Context, Harness) to ensure client project success

When AI writes code, requirements definition shifts "upstream"

With the arrival of tools like Claude Code, Cursor 3, and GitHub Copilot CLI, the cost of code generation itself has dropped close to zero. It is no longer unusual to see AI handling 80% of implementation hours on development teams.

However, what teams are actually experiencing is that ambiguity further upstream translates directly into ambiguity in deliverables. When you present requirements to AI, any vagueness in the author's intent is exposed at double the speed.

In April 2026, the popular Zenn article titled "The more AI writes code, the further upstream requirements definition moves — The Spec, Context, and Harness three-layer architecture" presented a practical breakdown of this phenomenon. This article unpacks that three-layer architecture from both contracting and client perspectives, explaining the new approach to requirements definition that both parties need to master.

What is the three-layer architecture?

Layer definitions

In this three-layer architecture, the information provided to an AI agent is organized into the following three tiers.

In traditional waterfall requirements definition, these were mixed together in a single specification document. In the AI era, mixing them degrades accuracy, making it essential to separate them into distinct layers.

Why separate into layers?

AI agents are sensitive to prompt structure. Even when given the exact same information, unorganized information significantly degrades accuracy.

• Providing only the Spec results in "output that does not fit existing code"
• Providing only the Context results in "an extension of existing code that fails to meet requirements"
• Lacking a Harness results in "output that runs, but nobody can verify"

Only when all three layers are in place can AI deliver "working code that matches the intended outcome."

Benefits for clients

1. Earlier exposure of misalignments

During the process of drafting the Spec, clients can identify the gap between what they envisioned and what is truly required. Discrepancies that previously went unnoticed until detailed design documents were drafted are now brought to light the moment the Spec is written.

2. Improved estimation accuracy

Requirements organized across the three layers provide a format that contractors can estimate with precision. Because it becomes clear which layers remain undefined, conversations become much sharper, allowing statements like "We cannot estimate this because it is not yet defined" or "We will include this in the design phase until resolved."

Common misalignments in website development estimates are also covered in our Website Development Cost Guide 2026, and for landing pages, in our LP Production Cost Guide.

3. Avoiding the misconception that "AI makes it cheap"

Requests like "Since AI is writing it, shouldn't it be cheap?" frequently arise, but the reality is that as implementation costs drop, the weight of requirements definition and verification increases. Using the three-layer architecture makes it straightforward to explain exactly where costs are allocated within an estimate.

Benefits for contractors

1. Clear delineation of responsibility boundaries

• Vague Spec → Client responsibility to redefine
• Outdated Context → Contractor updates it, or client provides an update
• Missing Harness → Explicitly define whether the client or contractor owns verification responsibility

The three-layer architecture is itself an explicit verbalization of responsibility boundaries. Because 80% of project disputes stem from ambiguities over who is responsible for what, this produces significant benefits.

2. Greater efficiency in AI utilization

Providing Spec, Context, and Harness separately improves the output quality of AI agents (such as Claude Code, Cursor, and Codex). The best practices shared in our Claude Code Workflow and Cursor 3 vs Claude Code guides also fundamentally converge on this three-layer architectural philosophy.

3. Greater knowledge reuse

The Context layer becomes an asset that can be reused across projects. Organizing industry domain dictionaries, internal coding guidelines, and security checklists will dramatically accelerate ramp-up times for subsequent projects.

Practical implementation steps

Phase 1: Spec drafting (client-led)

First, the client drafts the following:

1. Purpose: Why build this?
2. Users and usage scenarios: Who uses it, when, and how?
3. Success criteria: What needs to be achieved for completion?
4. Constraints and prohibited actions: What must not be done?
5. Non-functional requirements: Performance, security, and availability

Implementation methods should not be written at this stage. Focus solely on the What and the Why.

Phase 2: Context gathering (joint collaboration)

• Existing systems and database design documents
• Internal coding guidelines and naming conventions
• Industry conventions and terminology glossaries
• Lessons learned from past projects

While the contractor organizes these materials, the client must supply the primary source content.

Phase 3: Harness design (contractor-led)

• Acceptance test cases
• CI/CD pipeline design
• Rollback procedures
• Post-release monitoring criteria

Phase 4: Launching the AI loop

Once the three layers are ready, provide the Spec, Context, and Harness sequentially to the AI agent and execute the following loop:

1. AI drafts the implementation
2. Automated evaluation via the Harness (tests)
3. AI fixes issues upon test failures
4. Humans review only "decision branches requiring human judgment"

A practical case study of this operational flow can be found in our article on KAUCHE's AI-assisted automated review and merge workflow.

Common failure patterns

1. The same person writes both the Spec and the Harness — Tests become biased toward the Spec, failing to catch omitted requirements.
2. Context relies on outdated information — The AI operates on six-month-old information, mass-producing bugs.
3. Attempting to write all three layers completely in one go — Specs constantly evolve. Start with a lean draft assuming iterative cycles.
4. Relying on human intuition to verify AI outputs — Without a Harness, reviews ultimately depend on the reviewer's mood.

Conclusion

While the era of "leave it to AI for speed" has arrived, it carries the side effect of refusing to tolerate upstream ambiguity.

• Core of three-layer architecture: Separate Spec (what), Context (under what premises), and Harness (how to verify)
• Client benefits: Early detection of misalignments, higher estimation accuracy, clearing up "AI makes it cheap" misunderstandings
• Contractor benefits: Clear responsibility boundaries, higher AI precision, reusable knowledge assets
• Implementation path: Build in sequence: Spec → Context → Harness → AI loop

As AI agents become more capable, a client's ability to clarify thought and a contractor's ability to structure requirements will increasingly determine project success. The time has come to rethink not just technical AI usage, but the business process of requirements definition itself.

At GleamHub, we provide upstream engineering services that include requirements definition partnership, Spec drafting, and Harness design support tailored for the AI agent era. If you find your team lost in AI development, please reach out to us.

---

References

• Zenn — The more AI writes code, the further upstream requirements definition moves
• Harness Engineering with AI Agents — Existing article
• Claude Code 2026 feature roundup