34.1 Requirements: what it should and shouldn't do
Overview and links for this section of the guide.
On this page
Scope Definition
Before writing any code, we define exactly what the assistant will and won't do. This prevents scope creep and keeps the project buildable in a weekend.
The core question: What's the minimum viable product that's actually useful?
Must-Have Features
The "Vibe Coder" assistant must:
| Capability | Description | Implementation |
|---|---|---|
| Read files | Access the current state of the filesystem | fs.readFileSync() with path validation |
| Respect ignore patterns | Never read .env, node_modules, or .git |
Parse .gitignore, add hardcoded blocklist |
| Propose edits | Generate diffs that can be reviewed and applied | Search/Replace block format (see 34.3) |
| Run safe commands | Execute read-only commands like npm test |
Command allowlist with timeout |
| Answer questions | Explain code, find patterns, navigate the repo | Standard chat with repo context |
Non-Goals (What to Cut)
To keep this buildable in a weekend, we will NOT build:
- A full IDE: We build a CLI or simple wrapper. We don't rebuild VS Code.
- Multi-modal vision: We won't ask it to look at screenshots of the app (yet).
- Autonomous agents: It will not run in a loop forever. One turn at a time: User Input → AI Thought → AI Action → User Approval.
- Real-time collaboration: No multiplayer editing, no shared sessions.
- Language server integration: No go-to-definition, no autocomplete. Just Q&A and diffs.
You will be tempted to add "just one more feature." Don't. Ship the MVP, use it on real work, then add features based on what you actually need.
Safety Requirements
The most important requirements are around safety:
// Safety Rule #1: Never auto-apply changes
const applyChange = async (diff) => {
console.log("Proposed change:");
console.log(diff);
const approved = await confirm("Apply this change? (y/n)");
if (!approved) {
console.log("Change rejected by user.");
return;
}
// Only now do we write to disk
await writeFile(diff.path, diff.newContent);
};
// Safety Rule #2: Command allowlist
const ALLOWED_COMMANDS = [
'ls', 'cat', 'grep', 'find', 'wc',
'npm test', 'npm run lint', 'npm run build',
'git status', 'git diff', 'git log'
];
const BLOCKED_PATTERNS = [
/rm\s+-rf/,
/git\s+push/,
/curl.*\|.*sh/,
/sudo/,
/chmod\s+777/
];The AI never edits a file without you seeing the diff first. This single rule prevents 90% of potential disasters. Even if the AI is 99% accurate, that 1% can delete your production database.
User Stories
To validate our scope, here are the core user stories we're building for:
Story 1: Code Navigation
User: "Where is the function that validates email addresses?"
AI: "Found `validateEmail` in `src/utils/validation.ts` at line 42.
It uses a regex pattern and is called from:
- src/components/SignupForm.tsx (line 28)
- src/api/users.ts (line 15)"Story 2: Code Changes
User: "Add a `createdAt` timestamp to the User model"
AI: "I'll need to update 3 files:
1. src/models/user.ts - Add the field
2. src/db/migrations/... - Create migration
3. src/api/users.ts - Include in responses
Here's the diff for file 1:
[shows diff]
Apply this change? (y/n)"Story 3: Explanation
User: "Explain what the `useAuth` hook does"
AI: "The `useAuth` hook in `src/hooks/useAuth.ts` manages
authentication state. It:
1. Reads the JWT from localStorage
2. Decodes it to get user info
3. Provides `login()`, `logout()`, and `user` to consumers
4. Automatically refreshes tokens before expiry"