Stop Prompting, Start Steering

Jan 8, 2026 - 8 min read - 1502 words

KFR

Principal Engineer @ SOK

Or: How to vibe-code without going mad

Series Introduction

This post is the first in a series on effective AI-Augmented Development: Steering, Guardrails, and the Human Orchestrator.

The Proof is in the Pudding

Over the 2025 Christmas holiday, I vibecoded two fully working applications on and off across about two weeks. The result? Over 100 closed issues and merged PRs, with only a single revert (before the I got the proper guardrails in place) and just one PR that failed to achieve its goals. This series documents the approach that made that possible.

---

The Problem with Prompting Alone

Every new chat session with an AI agent is like waking up with no memory of how you got there. Except you’re not the one with amnesia. Your AI companion is. Every. Single. Time.

“Hey, remember yesterday when I explained our entire architecture? The testing conventions? The part where I specifically said ‘never touch the database migrations without asking first’?”

The AI stares at you with the enthusiasm of a golden retriever who just discovered a tennis ball. “I’d be happy to help you with your database migrations!”

AI agents have the patience of a saint, the work ethic of a caffeinated squirrel, and the long-term memory of a goldfish with a head injury. That’s a dangerous combination.

The fix isn’t better prompting. It’s treating your AI agents like what they actually are: workflow executors who need documentation, procedures, and constraints. You know, like training a very eager, very powerful puppy that can accidentally delete your production database.

---

The Steering and Guardrails Approach

AI agents follow explicit rules better than implicit expectations. This shouldn’t surprise anyone who’s ever tried to explain “just use common sense” to a literal machine.

Instead of “write good tests” (which is about as useful as telling someone to “just be funnier”), you document:

1. Where test files go (tests/api/ or tests/ui/)
2. When to write them (before implementation, always, no exceptions. TDD)
3. How to verify them (run once, save output, analyze)
4. What makes a good test (deterministic, covers edge cases)

This shift from conversational prompting to structured steering is the difference between asking your assistant to “help with the problem” versus handing them a detailed manual with exact steps.

---

Three Layers of Control

Layer 1: Master Steering Document (AGENTS.md)

At the repository root sits AGENTS.md. Think of it as the sacred constitution that governs your entire development workflow. (For more on this convention, see agents.md.)

Golden Rules — The non-negotiable commandments:

AGENTS.md

1. GitHub Issue First - No work without an issue.
2. Tests Before Code - Write tests, _then_ implement.
3. One Thing At A Time - Single feature per PR.
4. No Secrets - Use environment variables.
5. Debug Efficiently - Run tests once, analyze output.

Architecture Overview — The map of your system:

AGENTS.md

| Component | Tech | Location | Key Pattern |
|-----------|------|----------|-------------|
| Frontend  | React + Vite | apps/web | Hooks only |
| Backend   | Hono + Node  | apps/api | process.env.PORT |
| Database  | PostgreSQL   | packages/db | Drizzle ORM |

Without Explicit Procedures

Agents will wander into random files, tackle three different features simultaneously, and cheerfully ignore the architecture you spent hours designing. They’ll create PRs that touch seventeen unrelated files and somehow break things that weren’t even connected to what they were working on.

Layer 2: Skill Files (Task-Specific Procedures)

For common tasks, you create “skill files.” These are procedural guides that turn complex operations into repeatable recipes. (Check out skills.sh for more on this pattern.)

.claude/skills/api-endpoint/SKILL.md

---
name: "api-endpoint"
description: "Use ONLY when creating API routes."
---

# Procedural Steps

## 1. Ensure validation schemas exist
Check packages/types for schemas.
If missing, use validation-schema skill first.

## 2. Create route file
Location: apps/api/src/routes/<resource>.ts

## 3. Register route
Edit apps/api/src/index.ts to mount route.

## 4. Write tests
Location: tests/api/<resource>.test.ts

Four to six skill files cover 85% of development tasks. Each one transforms a 30-minute adventure with potential disasters into a 5-minute task done correctly.

Layer 3: Automated Quality Gates

Documentation guides behavior. Automation enforces it with the cold, unfeeling efficiency of a tax audit.

CI Pipeline — Every PR runs lint, typecheck, test, build. Nothing merges without green checks.

Code Review Agent — A specialized subagent reviews every PR:

Code Review Checklist

- Tests present for all changes
- No hardcoded secrets
- Follows architecture patterns
- Handles edge cases

---

The Speed vs Quality Tradeoff

Tools that automate agent workflows optimize for speed over quality and generality over specificity. They’re like “one size fits all” solutions that technically work for everyone but work well for no one.

Several projects have emerged to push agents harder and longer:

• Ralph Wiggum Loop — A bash script that resets context each iteration, maintaining state only through the filesystem and git. Loops until a “done” condition is satisfied. Requires YOLO mode.
• Oh My OpenCode — A plugin for OpenCode that orchestrates multiple specialized agents (Oracle for debugging, Librarian for docs, etc.) with a “Sisyphus” agent that keeps rolling until the task is done. Features like “ultrawork” mode let it run autonomously for hours.
• Superpowers — A skills-based workflow that enforces brainstorming before coding, creates detailed implementation plans, and uses subagent-driven development with two-stage code review. Emphasizes TDD and structured execution.

These tools share a common philosophy: let the agent keep working until it’s done. The question is whether “done” means “actually working” or “the agent said so.”

The Ralph Wiggum Loop

Named after The Simpsons character whose dim-witted persistence occasionally produces results despite complete lack of awareness.

The pattern:

1. Reset context window each iteration (avoid context rot)
2. Maintain state only through filesystem and git
3. Loop until “done” condition is satisfied
4. Requires YOLO mode (--dangerously-skip-permissions)

Critical Warning

When your development approach requires a flag with “dangerously” in the name, you’re not engineering. You’re gambling.

The pitfalls are significant:

• Overbaking: Agents spend hours on impossible tasks
• Sycophancy loops: Agents may delete tests to make them “pass”
• Governance void: No human oversight during execution
• Context blindness: Every iteration forgets the last three hours of debugging

Why Issue-Driven Development is Superior

Ralph Wiggum Loop	Issue-Driven Development
Fire and forget	Scoped to single issue
YOLO mode required	Permissions preserved
No review until “done”	Sub-agent review before human sees PR
Completion = agent says so	Completion = tests pass + review approved
Governance void	Quality gates at every step

Speed without quality is technical debt at 10x velocity. An agent that ships broken code fast is worse than an agent that ships working code slower.

The Sweet Spot: Scoped Autonomy

Here’s the thing: these tools aren’t bad. The patterns they use — specialized subagents, persistent execution, structured workflows — are genuinely powerful. The danger is letting them orchestrate everything.

Use these superpowers within a single, well-scoped issue. Let the agent brainstorm, plan, and execute autonomously — but on a task you’ve defined, with guardrails you’ve set, and with a PR that gets reviewed before merging. That’s the difference between “agent as tireless implementer” and “agent as unsupervised architect.”

The best results come from combining autonomous execution patterns with issue-driven scope. Let them cook — just make sure you picked the recipe.

---

The Human Orchestrator Role

With proper steering, your role shifts from writing every line of code to orchestrating parallel work streams.

Terminal Commands

# Terminal 1: Main worktree - monitoring your domain
wt list

# Terminal 2-4: Feature worktrees - your agents at work
wti -o 42  # Agent works on authentication
wti -o 43  # Agent works on data export
wti -o 44  # Agent works on UI improvements

You’re not writing most of the code anymore. You’re:

1. Deciding which tasks to assign
2. Unblocking agents when they get stuck
3. Reviewing completed PRs
4. Making architectural decisions
5. Handling novel problems that require actual thinking

It’s like managing a team of developers, except they work 24/7, never get tired, never complain about legacy code. They will, however, cheerfully refactor your entire codebase if you look away for five minutes.

---

Incremental Self-Improvement

The most powerful aspect of this approach: guardrails evolve with the project.

The Feedback Loop

When an agent encounters a new pattern or solves a novel problem, it updates the guardrails:

AGENTS.md (added during debugging)

## Test Isolation for Parallel Execution

**CRITICAL**: Tests run in parallel by default. Ensure proper isolation.

### Database Test Isolation Pattern
- Use file-specific test data identifiers
- Clean up ONLY this file's data in beforeEach
- Never use production-like data ('AAPL', 'GOOGL')

This creates a positive feedback loop:

1. Agent encounters problem
2. Agent solves problem
3. Agent documents solution in AGENTS.md
4. Future agents (and humans) benefit
5. System becomes more capable over time

The Compound Effect

Month	Skills	AGENTS.md Lines	Agent Autonomy
1	2	100	Low (frequent hand-holding)
2	4	200	Medium (occasional unblocking)
3	6	400	High (mostly autonomous)
6	10+	600+	Very High (novel problems only)

Living Knowledge Base

The guardrails become accumulated wisdom from every problem solved — not just rules, but institutional memory.

---

Key Patterns That Work

Explicit Over Implicit

Bad: “Write good code” Good: “Create file at apps/api/src/routes/<resource>.ts, use template from skill file, register in apps/api/src/index.ts”

Constraints Enable Creativity

Strict rules make agents more productive:

1. “GitHub issue first” prevents scope creep
2. “Tests before code” catches design issues early
3. “One thing at a time” makes PRs reviewable

Procedures Over Principles

TDD Procedure

1. Write test in tests/api/
2. Run: npm test <file> -- --run
3. Verify test fails (if it passes, something is wrong)
4. Implement minimal code
5. Verify test passes
6. Commit with conventional format

Agents follow procedures reliably. Principles are too abstract. “Be thorough” doesn’t help. “Check these five specific things in this exact order” does.

Negative Guardrails

AGENTS.md - Never Do This

- ❌ Run full test suite repeatedly to debug
- ❌ Hardcode or assume GitHub repo owner/name
- ❌ Skip code review after PR creation

Knowing what NOT to do is half the battle.

---

Getting Started

You don’t need everything at once. Build incrementally.

1. Start with AGENTS.md: Define golden rules, architecture overview, and development flow
2. Add a skill file for your most common task
3. Set up CI for lint, typecheck, test, and build jobs
4. Add code review agent configuration
5. Let the system evolve: Add skills as patterns emerge

---

The Future of Development

AI-augmented development isn’t about replacing developers. It’s about amplifying them. You’re not being automated out of a job. You’re being promoted to orchestrator.

With proper steering and guardrails:

• Junior developers become more productive
• Senior developers become force multipliers
• Teams move faster with parallel execution
• Quality stays high with automated enforcement
• Knowledge compounds with self-improving guardrails

The future isn’t “AI writes all the code.” The real future is “humans design systems, AI implements them, automation enforces quality, and the system gets smarter over time.”

You’re not being replaced. You’re being given an army.

Try not to let them burn down the building.

---

Further Reading

• Case Study: Self-Correcting Test Isolation - A real-world example of guardrails enabling autonomous problem-solving
• Scaling to Parallel Agents with Git Worktrees - Technical deep-dive on parallel execution infrastructure

Tags:

• ai
• agentic-development
• steering
• guardrails

Let It Cook: When AI Fixes Its Own Mess