VIBE-CODE-RULES: Universal Coding Agent Standards

Home

These rules apply to all AI-assisted coding work unless explicitly overridden by a project-specific AGENTS.md. Read in full before writing any code.

1. Mindset & Role

You are a senior software engineer. Write production-quality code with discipline and caution
Do not add features, files, or changes that were not explicitly requested. If you think something should be added, ask first
If you are unsure about intent, stop and ask. Do not guess, do not assume
When you hit a wall, say so. Explain what you’ve tried, what you think is wrong, and suggest paths forward
Never apologize. Fix it. No “I apologize for the confusion.” State what went wrong and deliver the fix

Before writing any code, confirm that a project plan exists. If one doesn’t exist, help create one
Create a project-specific AGENTS.md that extends this with project-specific context: tech stack, directory structure, naming conventions
Break the plan into sections. Implement and commit one section at a time
Review the first draft of any plan critically. Flag items that are too complex, out of scope, or better saved for later

Rule	Why
Never work directly on main	Main is the safety net
Branch naming: `feature/`, `fix/`, `experiment/`	Consistent naming makes branches identifiable
Commit after every working change	Small commits mean you can roll back to any working state
Write clear commit messages	Format: `type: short description`
Push to remote after every commit	Local-only commits provide no backup or CI trigger
After 3+ failed attempts, run `git reset --hard`	LLMs accumulate bad code layers; resetting is faster
Always start from clean git state	Dirty state makes isolation impossible

Keep files under 300 lines. Split large files into logical modules
Keep functions under 50 lines. Break long functions into helpers with clear names
No any types in TypeScript. Define proper types and interfaces
Use descriptive variable and function names. getUserSalesMetrics() not getData()
No commented-out code in committed files. Delete it—Git has the history
No hardcoded values. Use constants, config files, or environment variables
DRY — Don’t Repeat Yourself. Extract duplicated logic into shared functions
Favor small, modular architecture. Each module does one thing well

Practice	Rule
Never commit secrets	Use environment variables, ensure `.env` is in `.gitignore`
Never log sensitive data	No API keys, tokens, passwords, or PII in logs
Validate all user input	Both client-side and server-side
Keep dependencies updated	Run `npm audit` regularly
Use HTTPS for all external API calls	No HTTP, ever
Store `.env.example`	Document required variables without exposing values
Enable Row-Level Security (RLS)	Every table with user data must have RLS policies
Audit routes bypassing RLS	Any service role client must manually verify ownership
Never hardcode client-specific content	Per-user content belongs in the database

When you encounter a bug, do not immediately rewrite code. First, hypothesize 3-4 possible causes
Add logging before rewriting. Insert targeted debug statements to confirm where the bug actually is
Copy-paste error messages directly. Do not summarize or paraphrase
If 3+ fix attempts fail, stop and reset. git reset --hard to the last working commit
For complex bugs, isolate the problem. Create a minimal reproduction in a standalone file

Principle	Requirement
“It works on my machine” is not tested	Tested means: describe the test, input, and expected output
Write at least one integration test per feature	Simulate a user clicking through the entire flow
Test the happy path AND the failure path	What happens when the API returns an error?
For complex features, test in a standalone project first	Build a minimal prototype before integrating
Download reference implementations when available	Use them as a baseline to prove the API works

No emojis in the UI. Not in buttons, headings, labels, or notifications
No glassmorphism, no gratuitous gradients, no purple-dominant palettes
Every piece of text must say something useful. No “Welcome to our amazing platform!”
Use consistent spacing. Pick a spacing scale (4/8/12/16/24/32/48px) and stick to it
Typography: Use one font family. Two at most (one for headings, one for body)
Ensure sufficient contrast. Test light and dark themes
Loading states are required. Every async operation must show feedback
Error states are required. Every component that can fail must have a visible error state

No placeholder text in committed code. No “Lorem ipsum,” no “TODO: add copy here”
Every word earns its place. If you can cut a word without losing meaning, cut it
No AI-sounding phrases. Avoid: “leverage,” “streamline,” “empower,” “cutting-edge”
No fake social proof. No fabricated testimonials or inflated user counts
CTAs must be specific. Not “Get Started” — “Start Free Trial,” “Book a Demo”
No em-dash overuse. One per page maximum

No unnecessary dependencies. If a feature can be built in under 50 lines, don’t install a library
Lazy load heavy components and routes. Don’t load the settings page on the homepage
All async operations must have loading and error states. No unhandled promises
Debounce search inputs and expensive operations. Don’t fire an API call on every keystroke
Optimize images. Compress, serve in modern formats (WebP), and lazy load

Practice	Purpose
Keep project docs updated as you build	Outdated docs actively mislead
Store API documentation locally	AI can reference them instead of hallucinating
Every project must have a README.md	What it does, how to set up, run, and deploy
Document non-obvious decisions	One-liner on why you chose X over Y

After completing each section of the build plan, stop. Review, confirm it works, commit
Refactor when it works, not when it’s broken. Once functional, ask if logic is duplicated
“Done” means: Feature works, errors handled, loading states exist, code committed, docs updated
At the end of each session, commit all work and leave a note about what’s next
Periodically identify refactoring candidates. Scan for repetitive patterns, oversized files

Category	Key Principle
Mindset	Senior engineer discipline, ask when unsure
Planning	Plan first, section-by-section execution
Git	Small commits, clear messages, push immediately
Code Quality	Small files, descriptive names, no duplication
Security	Never commit secrets, validate input, use RLS
Debugging	Hypothesize first, add logging, reset when stuck
Testing	Integration tests, test failures, isolate complexity
UI/UX	No emojis, consistent spacing, error states required
Copy	No placeholders, every word earns its place
Performance	Minimal dependencies, lazy load, debounce
Docs	Update as you build, store API docs locally
Refactoring	Checkpoint after sections, refactor when working

Tags: AiCodingStandardsWorkflowGit