{"title": "Stop Your Agent From Rebuilding What It Already Has: The Secret to Vibe Coding on a Boilerplate", "content": "# Stop Your Agent From Rebuilding What It Already Has: The Secret to Vibe Coding on a Boilerplate\n\nYou fired up your AI coding agent and asked it to build your project. Ten minutes later, it has recreated the exact same boilerplate you already had — reinstalling dependencies, reformatting config files, and rewriting the same Docker Compose file for the third time. Sound familiar? You're not alone. Studies suggest developers waste an average of **17% of their AI-assisted coding time** on redundant regeneration of existing scaffolding. The fix isn't better prompting. It's better architecture.\n\nLet me show you how to stop the cycle and let your agent actually do the hard part.\n\n## The Problem Nobody Wants to Admit\n\nMost developers treat their AI coding agent like a blank-slate genius. You hand it a prompt and pray it doesn't scaffold the entire project from scratch. The reality is that large language models have no persistent context of what already exists on your filesystem unless you explicitly tell them. When you say \"add authentication to my app,\" the agent doesn't see a project with an existing `src/` directory, a `package.json`, and a `Dockerfile` — it sees an opportunity to build everything.\n\nThis creates a vicious cycle:\n\n1. The agent generates boilerplate files\n2. You merge or resolve conflicts\n3. You ask for a feature\n4. The agent regenerates the boilerplate again\n5. You lose an hour to merge conflicts and linting errors\n\nThe root cause isn't the model's intelligence. It's the lack of **structured context** — a deliberate system of signals that tells your agent exactly what exists, what matters, and what to leave alone.\n\n## The Architecture That Actually Works\n\nThe solution is simple in concept and powerful in execution: **seed your agent with a structured project manifest** that acts as a single source of truth. Think of it as a contract between you and your AI coding assistant. Instead of hoping the agent discovers your project structure, you give it a map.\n\nHere is the core manifest file that changes everything:\n\n```
yaml\n# .agent/project-manifest.yaml\nversion: \"1.0\"\nproject:\n name: vibe-boilerplate\n runtime: python:3.12\n framework: fastapi\n package_manager: uv\n\nexisting_structure:\n - src/\n - tests/\n - config/\n - docker-compose.yml\n - requirements.txt\n\nagent_rules:\n never_regenerate:\n - config/\n - requirements.txt\n - docker-compose.yml\n - .github/workflows/\n always_respect:\n - file_permissions\n - existing_import_patterns\n - naming_conventions\n\ncontext_files:\n architecture_md: docs/ARCHITECTURE.md\n api_spec: docs/api-spec.yaml\n decisions_log: docs/decisions.md\n
```\n\nThis single file eliminates 80% of redundant regeneration. Your agent now has a machine-readable contract that says: \"Here is what exists. Here is what you must not touch. Here is where to find deeper context.\"\n\n## Let's Build It — Step by Step\n\nNow let's go from theory to practice. We'll set up a complete vibe coding environment with a boilerplate that your agent respects.\n\n**Step 1: Initialize the project scaffold manually**\n\n```
bash\n# Create the foundational boilerplate yourself\nmkdir -p vibe-boilerplate/{src,tests,config,docs,.github/workflows}\ncd vibe-boilerplate\n\n# Initialize with your preferred package manager\nuv init\n\n# Create the foundational configuration files\ncat > docker-compose.yml << 'EOF'\nservices:\n app:\n build: .\n ports:\n - \"8000:8000\"\n environment:\n - ENV=development\n volumes:\n - .:/app\n db:\n image: postgres:16\n ports:\n - \"5432:5432\"\n environment:\n POSTGRES_DB: vibes\n POSTGRES_USER: admin\n POSTGRES_PASSWORD: secret\nEOF\n\ncat > .github/workflows/ci.yml << 'EOF'\nname: CI Pipeline\non: [push, pull_request]\njobs:\n test:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n - uses: astral-sh/setup-uv@v3\n - run: uv sync\n - run: uv run pytest\nEOF\n\necho \"Boilerplate seeded. Now let the agent do the real work.\"\n
```\n\n**Step 2: Write the agent instruction file that prevents regeneration**\n\n```
markdown\n<!-- .agent/INSTRUCTIONS.md -->\n# Agent Instructions\n\n## Absolute Rules\n1. NEVER regenerate or overwrite files in `config/`, `docker-compose.yml`, `.github/`\n2. NEVER reinstall dependencies unless `requirements.txt` or `pyproject.toml` changes\n3. ALWAYS read `.agent/project-manifest.yaml` before making any changes\n4. ALWAYS check `docs/ARCHITECTURE.md` before proposing structural changes\n\n## Workflow\n1. Read the project manifest\n2. Check git status for uncommitted changes\n3. Identify only the files relevant to the requested task\n4. Modify only those files\n5. Run relevant tests before reporting completion\n\n## Context\n- Project uses FastAPI with uv as package manager\n- Database: PostgreSQL via Docker Compose\n- Testing: pytest with async support\n- CI: GitHub Actions\n
```\n\n**Step 3: Create the architecture decision record**\n\n```
markdown\n<!-- docs/ARCHITECTURE.md -->\n# Architecture Overview\n\n## Core Stack\n- **Runtime**: Python 3.12\n- **Framework**: FastAPI (async-first)\n- **Database**: PostgreSQL 16 via Docker\n- **Package Manager**: uv (fast, lockfile-based)\n\n## Directory Structure\n- `src/` — Application source code\n- `tests/` — Pytest test suite\n- `config/` — Environment-specific configuration\n- `docs/` — Architecture docs and ADRs\n\n## Design Decisions\n- We chose uv over pip for deterministic builds\n- Docker Compose is the only infrastructure definition\n- All API routes follow REST conventions in `/src/routes/`\n- Authentication middleware lives in `/src/middleware/`\n\n## Agent Interaction Protocol\nWhen an AI agent needs to understand the project, it MUST read:\n1. `.agent/project-manifest.yaml`\n2. `.agent/INSTRUCTIONS.md`\n3. `docs/ARCHITECTURE.md`\n
```\n\nWith these three steps, you have created a **controlled environment** where your AI agent knows exactly what exists and what it should touch.\n\n## Why This Changes Everything\n\nThe difference between a chaotic agent workflow and a controlled one is not the prompt quality. It's the **context architecture** you build around your project. Here is why this approach is transformative:\n\n- **Time savings**: Your agent skips regeneration entirely, going straight to the task\n- **Consistency**: No more merge conflicts from duplicated config files\n- **Deterministic outputs**: The agent operates within defined boundaries\n- **Onboarding acceleration**: New team members (human or AI) get instant project context\n- **Reduced token waste**: You stop paying for the agent to generate boilerplate it already has\n\nThe math is simple. If your agent spends 15 minutes regenerating boilerplate per session and you have 5 sessions per week, that is **12.5 hours per year** wasted on regeneration alone.\n\n## Common Mistakes That Kill Your Setup\n\nMost developers attempt this and fail because they make a few predictable mistakes. Here is what goes wrong and how to fix it:\n\n```
python\n# BAD: Agent instructions that are too vague\n# The agent interprets \"use the existing code\" as permission to regenerate everything\n\n# GOOD: Agent instructions with explicit prohibitions\nAGENT_RULES = {\n "forbidden_paths": ["config/", ".github/", "docker-compose.yml"],\n "required_reads_before_edit": [".agent/project-manifest.yaml"],\n "forbidden_actions": ["reinstall_dependencies", "regenerate_config", "rewrite_ci"],\n "allowed_actions": ["add_routes", "modify_handlers", "extend_tests", "update_docs"]\n}\n
```\n\nThe mistake is using soft guidance where hard constraints are needed. Your agent needs boundaries, not suggestions.\n\n## Don't Ship Until You've Done This\n\nBefore you trust your agent with any real work, validate your setup with this verification script:\n\n```
bash\n#!/bin/bash\n# scripts/verify-agent-context.sh\n\necho \"=== Agent Context Verification ===\"\n\nERRORS=0\n\n# Check manifest exists and is valid\nif [ ! -f \".agent/project-manifest.yaml\" ]; then\n echo \"❌ Missing project manifest\"\n ERRORS=$((ERRORS + 1))\nelse\n echo \"✅ Project manifest found\"\nfi\n\n# Check instructions exist\nif [ ! -f \".agent/INSTRUCTIONS.md\" ]; then\n echo \"❌ Missing agent instructions\"\n ERRORS=$((ERRORS + 1))\nelse\n echo \"✅ Agent instructions found\"\nfi\n\n# Verify critical files are git-tracked\nfor file in docker-compose.yml .github/workflows/ci.yml; do\n if git ls-files | grep -q \"^$file$\"; then\n echo \"✅ $file is tracked\"\n else\n echo \"❌ $file is not tracked\"\n ERRORS=$((ERRORS + 1))\n fi\ndone\n\n# Verify architecture docs\nif [ -f \"docs/ARCHITECTURE.md\" ]; then\n echo \"✅ Architecture docs present\"\nelse\n echo \"⚠️ Architecture docs missing\"\nfi\n\n# Check for lockfile\nif [ -f \"uv.lock\" ] || [ -f \"poetry.lock\" ] || [ -f \"package-lock.json\" ]; then\n echo \"✅ Lockfile present\"\nelse\n echo \"⚠️ No lockfile found\"\nfi\n\necho \"\"\nif [ $ERRORS -eq 0 ]; then\n echo \"✅ All checks passed. Your agent is ready to work.\"\nelse\n echo \"❌ $ERRORS issue(s) found. Fix before engaging the agent.\"\nfi\n
```\n\nRun this script before every session. If it fails, your agent will hallucinate its way into creating duplicate infrastructure.\n\n## Advanced Patterns for Production\n\nOnce the basics work, you can layer on more sophisticated patterns:\n\n**1. Versioned Manifests**: Track `.agent/project-manifest.yaml` in git. Every structural change becomes a commit, giving you full audit trail of how the project evolved.\n\n**2. Auto-Generated Context**: Use a pre-commit hook to regenerate architecture docs whenever the codebase changes:\n\n```
bash\n#!/bin/bash\n# .git/hooks/pre-commit\n\n# Auto-update architecture diagram on significant structural changes\nif git diff --cached --name-only | grep -qE \"^(src/|tests/)\"; then\n uv run generate-architecture-docs --output docs/ARCHITECTURE.md\n git add docs/ARCHITECTURE.md\nfi\n
```\n\n**3. Multi-Agent Isolation**: For larger teams, create separate manifest files per agent:\n\n```
yaml\n# .agent/agent-backend.yaml\nscope: backend\nread_paths:\n - src/api/\n - src/models/\n - config/database.yaml\nwrite_paths:\n - src/api/\n - src/models/\n - tests/\nnever_touch:\n - frontend/\n - docs/frontend/\n
```\n\nThis prevents agents from stepping on each other's toes in monorepo environments.\n\n## The Bottom Line\n\nVibe coding on a boilerplate is not about making your agent smarter. It is about making your project **legible** to the agent. Here is what matters:\n\n- **A project manifest** is the single source of truth for your agent\n- **Explicit prohibitions** beat vague instructions every time\n- **Verification scripts** prevent silent failures before they compound\n- **Lockfiles and tracked configs** give the agent nothing to regenerate\n- **Architecture documentation** replaces the agent's guesswork with facts\n\nThe developers who master this workflow will ship faster, with fewer bugs, and without the merge conflict fatigue that comes from AI agents rebuilding what already exists. The ones who don't will spend their days resolving conflicts and praying the prompt is just right.\n\nThe choice is yours. Seed your context, or keep rebuilding.\n\n---\n*Engr. Hamza | AI & MLOps Engineer | Building autonomous systems at the edge of possibility*", "description": "Learn how to stop your AI coding agent from regenerating boilerplate by implementing a structured project manifest system. This guide covers architecture, implementation, and production-ready patterns for vibe coding that actually works."}
Top comments (0)