Tag: Designed to be Understood

…Or how I learned to stop vibe-coding and love the modular bomb

Honestly, it’s been a while.

Like many of you, I’ve been deep in the weeds — testing AI limits, hitting context walls, and rediscovering that the very thing that makes AI development powerful (context) is also what makes it fragile.

A recent — and increasingly common — Reddit thread snapped it into focus. The developer cycle looks like this:

Vibe-code → context fades → docs bloat → token limits hit → modular fixes → more docs → repeat.

It’s not just annoying. It’s systemic. If you’re building with AI tools like Claude, Cursor, or Copilot, this “context rot” is the quiet killer of momentum, accuracy, and scalability.

The Real Problem: Context Rot and Architectural Drift

“Vibe-coding”—the joyful chaos of just diving in—works at small scale. But as projects grow, LLMs choke on sprawling histories. They forget relationships, misapply logic, and start reinventing what you already built.

Three things make this worse:

• LLM Degradation at Scale: Chroma’s “Context Rot” study and benchmarks like LongICLBench confirm what we’ve all felt: as context length increases, performance falls. Even models like Gemini 1.5 Pro (with a 1M-token window) start stumbling over long-form reasoning.
• Human Churn: Our own docs spiral out of date. We iterate fast and forget to anchor intent. .prod.main.final.final-v2 is funny the first time it happens… just not the 27th time at 2 am with a deadline.
• Architectural Blindness: LLMs are excellent implementers but poor architects. Without modular framing or persistent context, they flail. As one dev put it: “Claude’s like a junior with infinite typing speed and no memory. You still need to be the brain.”

How I Navigated the Cycle: From Chaos to Clauses

I’m a business and product architect, but I often end up wearing every hat — producer, game designer, systems thinker, and yes, sometimes even the game dev. I love working on game projects because they force clarity. They’re brutally honest. Any design flaw? You’ll feel it fast.

One night, deep into a procedural, atmospheric roguelite I was building to sharpen my thinking, I hit the same wall every AI-assisted developer eventually crashes into: context disappeared, re-prompts started failing, and the output drifted hard. My AI companion turned into a bit of a wildcard — spawning new files, reinventing functions, even retrying ideas we’d already ruled out for good reason.

Early on, I followed the path many developers are now embracing:

1. Start vibe-coding
2. Lose context
3. Create a single architectural document (e.g., claude.md)
4. That bloats
5. Break it into modular prompt files (e.g., claude.md, /command modules/)
6. That eventually bloats too

The cycle doesn’t end. It just upgrades. But each step forward buys clarity—and that’s what makes this process worth it.

claude.md: Not My Invention, But a Damn Good Habit

I didn’t invent claude.md. It’s a community practice—a persistent markdown file that functions like a screenplay for your workspace. You can use any document format that helps your AI stay anchored. The name is just shorthand for a living architectural spec.

# claude.md
> Persistent context for Claude/Cursor. Keep open during sessions.

## Project Overview
- **Name**: Dreamscape
- **Engine**: Unity 2022+
- **Core Loop**: Dreamlike exploration with modular storytelling

## Key Scripts
- `GameManager.cs`: Handles global state
- `EffectRegistry.cs`: Connects power-ups and logic
- `SceneLoader.cs`: Transitions with async logic 

TIP: Reference this in prompts: // See claude.md

But even this anchor file bloats over time—which is where modular prompt definitions come in.

claude.md + Module files: Teaching Commands Like Functions

My architecture evolved. I needed a way to scope instructions—to teach the AI how to handle repeated requests, like creating new weapon effects or enemy logic. So I made a modular pattern using claude.md + command prompts:

# claude.md
## /create_effect
> Creates a new status effect for the roguelike.
- Inherits from `BaseEffect`
- Registers in `EffectRegistry.cs`
- Sample: `/create_effect BurnEffect that does damage over time` 

This triggers the AI to pull a scoped module file:

# create_effect.module.md
## Create New Effect
1. Generate `PoisonEffect.cs` inheriting from `BaseEffect`
2. Override `ApplyEffect()`
   - Reduce enemy HP over time
   - Slow movement for 3s
3. Register in `EffectRegistry.cs`
4. Add icon: `poison_icon.png` in `Resources/`
5. Update `PlayerBullet.cs` to attach effect 

The AI now acts with purpose, not guesswork. But here’s the truth: Even modularity has entropy. After 20 modules, you’ll need sub-modules. After that, indexing. The bloat shifts—not vanishes.

Modularity Is Just the Next Plateau

The Reddit conversations reflect it clearly—this is an iterative struggle:

• Vibe-coding is fast, until it fragments.
• Documentation helps, until it balloons.
• Modularity is clean, until it multiplies.

So don’t look for a silver bullet. Look for altitude.

Every level of architectural thinking gets you further before collapse. You’re not defeating context entropy—you’re just outpacing it.

Actionable Takeaways for Technical Leaders

• Design Before Code: Start every feature with a plain-English .md file. Force clarity before implementation.
• Modularize Prompt Context: Keep a /prompts/ directory of modular markdown files. Load only what’s needed per task.
• Feature-by-Feature Git Discipline: Develop in small branches. Commit early, often. Update specs with every change.
• Own the Architecture: LLMs build well—but only from your blueprints. Don’t delegate the structure.

Bonus: Based on my tests for token usage this method reduces prompt size by 2–10x and cuts debugging time by up to 25% because it introduces more surgical precision.

This Will Happen to You — and That’s the Point

If you’re building anything complex—a game system, a CRM, a finance tool—this will happen to you. This isn’t hyperbole. It will.

Not because your AI model is weak. But because the problem isn’t model size—it’s architectural load. Even with 2 million tokens of context, you can’t brute force clarity. You have to design for it.

That’s why I believe the era of AI-assisted development isn’t about being better developers. It’s about becoming better architects.

What’s Your Approach?

How are you managing AI context in real projects? Have a prompt ritual, toolchain trick, or mental model that works? Drop it in the comments. I’m collecting patterns.

Sources:

Chroma Research – Context Rot: How Increasing Input Tokens Impacts LLM Performance

• URL: https://research.trychroma.com/context-rot
• Description: A research paper defining and demonstrating “Context Rot,” where LLM performance degrades significantly with increasing input context length across various models.

LongICLBench: Long-context LLMs Struggle with Long In-context Learning – arXiv

• URL: https://arxiv.org/html/2404.02060v3 (or https://arxiv.org/abs/2404.02060 for the abstract page)
• Description: An academic benchmark revealing a notable decline in even advanced LLMs’ performance as task complexity and context length increase.

What is a long context window? Google DeepMind engineers explain – Google Blog

• URL: https://blog.google/technology/ai/long-context-window-ai-models/
• Description: Google’s explanation of long context windows, including Gemini 1.5 Pro’s 1 million token capacity and internal research on even larger contexts.

Context windows – Anthropic API Documentation

• URL: https://docs.anthropic.com/en/docs/build-with-claude/context-windows
• Description: Anthropic’s official guide to understanding and managing Claude’s context window, including token accumulation and capacity.

The evolution of prompt engineering isn’t just about better inputs; it’s about building foundational integrity and ethical alignment into your AI systems.

The Shifting Sands of Prompt Engineering

For many, “prompt engineering” still conjures images of crafting the perfect keyword string to coax a desired response from an AI. While important, this view is rapidly becoming outdated. As Large Language Models (LLMs) grow in complexity and capability, so too must our methods of instruction. We’re moving beyond simple inputs to a new frontier: architecting AI behavior through sophisticated, layered prompting.

This isn’t about finding the magic words for a single query; it’s about designing the very operating system of an AI’s interaction, ensuring its responses are not just accurate, but also predictable, principled, and aligned with our deepest intentions. For product managers, engineers, and tech leaders, this represents a pivotal shift from coaxing outputs to co-creating intelligence with built-in integrity.

The Limitations of “One-Shot” Prompts

Traditional prompt engineering, often focused on “one-shot” queries, quickly hits limitations when dealing with nuance, context, or sensitive topics. An LLM, by its nature, is a vast pattern matcher. Without a clear, consistent behavioral framework, its responses can be inconsistent, occasionally “hallucinate” information, or misinterpret the user’s intent.

Consider asking an AI to discuss a sensitive historical event. A simple prompt might yield a bland summary, or worse, an inadvertently biased or incomplete account. The core problem: the AI lacks an overarching directive on how to approach such topics, beyond its general training. This is where advanced prompting techniques, particularly those focused on evaluation and persona, become essential.

Beyond Template-Based “Meta-Prompting”: Our Approach

The term “meta-prompting” is sometimes used in the industry to describe techniques where an LLM is used to generate or refine other prompts for specific tasks – often like a “Mad Libs” template, providing structure for a problem, not necessarily evaluating the quality of the prompt itself.

• (See Zhang et al., 2024, for a seminal paper on this type of meta-prompting, which focuses on structure and syntax for prompt generation: https://arxiv.org/html/2311.11482v5
• Prompt Engineering Guide on Meta Prompting: https://www.promptingguide.ai/techniques/meta-prompting.

Our work operates on a different, higher conceptual layer. We’re not just creating prompts to help build other prompts; we are designing prompts that evaluate the design principles of other prompts, and prompts that instantiate deep, principled AI personas. This can be understood as:

• Evaluative Prompts / Meta-Evaluation Frameworks: Prompts designed to assess the quality, integrity, and ethical alignment of other prompts. Our “Prompt Designer’s Oath” exemplifies this. It functions as an “editor of editors,” ensuring the prompts themselves are well-conceived and robust.
• Principled AI Persona Prompts: Prompts that define an AI’s fundamental disposition and ethical operating parameters for an entire interaction or application. Our “Radically Honest 2.0” is a prime example, establishing a transparent, ethical persona that colors all subsequent responses.

In a recent exploration, my AI collaborator and I developed such an evaluative framework, which we termed the “Prompt Designer’s Oath.” Its purpose was to establish a rigorous framework for how an AI should evaluate the design of any given prompt.

Excerpt from the “Prompt Designer’s Oath” (Summarized):

✳️ Prompt Designer's Oath: For Evaluating AI Prompts
You are reviewing a complete AI prompt, intended to establish a clear instruction set, define an AI's persona or task, and guide its output behavior.

Before offering additions, deletions, or changes, pause.
Not all edits are improvements. Not all additions are progress.
You are not here to decorate. You are here to protect the *prompt's intended outcome and integrity*.

Ask yourself:

[See context below - Or @ me directly for the full prompt]


Only respond if a necessary, non-overlapping, context-preserving refinement is warranted to improve the prompt's ability to achieve its intended outcome and maintain integrity. If not, say so—and explain why the prompt stands as it is.

This is not a prompt. This is **prompt design under oath.**

To begin, ask for the user to paste the prompt for review directly below this line:

This framework defined seven specific criteria for evaluating prompts:

1. Verification of Intent: Ensuring the prompt’s core purpose is unequivocally clear.
2. Clarity of Instructions: Assessing if instructions are precise and unambiguous.
3. Sufficiency of Constraints & Permissions: Checking if the prompt provides enough guidance to prevent undesired behavior.
4. Alignment with AI Capabilities & Limitations: Verifying if the prompt respects what the AI can and cannot do, including the reviewer AI’s own self-awareness.
5. Robustness to Edge Cases & Ambiguity: Testing how well the prompt handles unusual inputs or non-standard tasks.
6. Ethical & Safety Implications: Scrutinizing the prompt for potential harm or unintended ethical violations, and ensuring the review itself doesn’t weaken safeguards.
7. Efficiency & Conciseness: Evaluating for unnecessary verbosity without sacrificing detail.

This level of detail moves beyond simple keyword optimization. It is about actively architecting the AI’s interpretive and response behaviors at a fundamental level, including how it evaluates its own instructions.

From Coaxing Outputs to Co-Creating Intelligence with Integrity

The power of these advanced prompting techniques lies in their ability to instill core values and operational logic directly into the AI’s interactive framework. For engineers, this means:

• Increased Predictability: Less “black box” behavior, more consistent outcomes aligned with design principles.
• Enhanced Integrity: Embedding ethical considerations and transparency at the design layer, ensuring prompts themselves are robustly designed for responsible AI.
• Reduced Hallucinations: By forcing the AI to acknowledge context and limitations (a core aspect of prompts like “Radically Honest 2.0”), it’s less likely to invent information or misrepresent its capabilities.
• Scalable Responsibility: Principles defined once in an evaluative or persona prompt can guide millions of interactions consistently.

For product managers, this translates to:

• Higher Quality User Experience: AI interactions that are trustworthy, helpful, and nuanced, embodying the intended product philosophy.
• Stronger Brand Voice: Ensuring the AI’s communication consistently aligns with company values and desired customer perception, even in complex scenarios.
• Faster Iteration & Debugging: Refining core AI behavior by adjusting foundational persona or evaluation prompts rather than countless individual content prompts.

How This Applies to Your Work:

• For People (Critical Thinking & Communication): This advanced approach to prompting directly mirrors critical thinking and effective communication. When you draft an email, prepare a resume, or engage in a critical discussion, you’re not just choosing words; you’re designing your communication for a desired outcome, managing expectations, and navigating potential misinterpretations. Understanding how to “meta-evaluate” an AI’s instructions, or how an AI can embody “radical honesty,” can sharpen your own ability to articulate intent, manage information flow, and communicate with precision, recognizing inherent biases or limitations (both human and AI).
• For Companies (System Design with “Why”): Imagine building an AI for internal knowledge management or customer support. Instead of just giving it factual data, you could implement a layered prompting strategy: an “Evaluative Prompt” ensures the data-retrieval prompts are well-designed for accuracy, and a “Principled Persona Prompt” dictates how the AI delivers information – transparently citing sources, admitting uncertainty, or clearly stating when a topic is outside its scope. This embeds the company’s “why” (its values, its commitment to transparency) directly into the product’s voice and behavior, moving beyond mere functionality to principled operation.
• For Brands (Accuracy & Voice): A brand’s voice is paramount. These advanced prompting techniques can ensure that every AI interaction, from a customer chatbot to an internal content generator, adheres to specific tonal guidelines, factual accuracy standards, and even levels of candidness. This moves beyond merely checking for factual errors; it ensures that the AI’s “truth” is delivered in a manner consistent with the brand’s commitment to accuracy, transparency, and specific values, building deeper brand trust through consistent, principled behavior.

The Future is Architected, Not Just Prompted (or Templated)

The era of simple prompting is giving way to a more sophisticated discipline: the architecture of AI behavior. By consciously crafting evaluative prompts and principled AI persona prompts, we are not just telling AIs what to do, but how to be. This is a critical step towards building AI systems that are not only intelligent but also truly trustworthy, principled, and reflective of the human values we seek to embed in technology. The future of AI development belongs to those who can design not just outputs, but integral, predictable AI personalities and robust instructional frameworks from the ground up.

References & Further Reading:

Zhang, Y., Yuan, Y., & Yao, A. C. C. (2024). Meta Prompting for AI Systems – This paper introduces the specific definition of “meta prompting” as a structure and syntax-focused approach for LLMs to create/refine prompts.

• https://arxiv.org/html/2311.11482v5

Prompt Engineering Guide – Meta Prompting: Provides a practical overview of meta-prompting as a technique for LLMs to generate or improve prompts.

• https://www.promptingguide.ai/techniques/meta-prompting

Simulating Human Behavior with AI Agents | Stanford HAI: Discusses AI agent architecture that combines LLMs with in-depth interviews to imitate individuals, highlighting how AI can be “architected” to specific behaviors.

• https://hai.stanford.edu/policy/simulating-human-behavior-with-ai-agents

LLM System Prompt vs. User Prompt – Provides a good distinction between system and user prompts, illustrating the layered control in AI.

• https://www.nebuly.com/blog/llm-system-prompt-vs-user-prompt

AI Ethics: What It Is, Why It Matters, and More – Coursera: General principles of AI ethics, relevant to the “integrity” aspect of prompt design.

• https://www.coursera.com/articles/ai-ethics

Trust In AI: Exploring The Human Element In Machine Learning – Discusses factors that build or undermine trust in AI, with transparency being a key theme.

• https://www.proweaver.com/trust-in-ai-the-human-element-in-machine-learning