Project Principles
Developmentproject-principlesProject Principles is an Agent Skill for development published in the vm0-ai/vm0 repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Core architectural and code quality principles that guide all development decisions in the vm0 project
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/vm0-ai/vm0/blob/HEAD/.claude/skills/project-principles/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/project-principles, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Project Principles Skill
This skill defines the fundamental design principles and coding standards for the vm0 project. These principles are MANDATORY for all code written in this project and should guide every development decision.
The Four Core Principles
1. YAGNI (You Aren't Gonna Need It) ⭐ CORE PRINCIPLE
Don't add functionality until it's actually needed.
Quick rules:
- Start with the simplest solution that works
- Avoid premature abstractions
- Delete unused code aggressively
- No "just in case" features
When coding: Ask "Do we need this NOW?" If not, don't add it.
→ For detailed guidelines and examples, read yagni.md
2. Avoid Defensive Programming
Let exceptions propagate naturally. Don't wrap everything in try/catch.
Quick rules:
- Only catch exceptions when you can meaningfully handle them
- Let errors bubble up to where they can be properly addressed
- Avoid defensive try/catch blocks that just log and re-throw
- Trust the runtime and framework error handling
When coding: Only use try/catch when you have specific error recovery logic.
→ For detailed guidelines and examples, read no-defensive.md
3. Strict Type Checking
Maintain type safety throughout the codebase. Never compromise on type checking.
Quick rules:
- Absolutely NO use of
anytype - Always provide explicit types where TypeScript can't infer
- Use proper type narrowing instead of type assertions
- Define interfaces and types for all data structures
When coding: If you see any, fix it. If types are missing, add them.
→ For detailed guidelines and examples, read type-safety.md
4. Zero Tolerance for Lint Violations
All code must pass linting without exceptions.
Quick rules:
- Never add eslint-disable comments
- Never add @ts-ignore or @ts-nocheck
- Fix the underlying issue, don't suppress the warning
- All lint rules are there for a reason - respect them
When coding: If lint fails, fix the code, not the linter.
→ For detailed guidelines and examples, read zero-lint.md
Quick Reference: Code Quality Checklist
Before writing any code, verify:
- ✅ Is this feature needed NOW? (YAGNI)
- ✅ Am I avoiding unnecessary try/catch? (No Defensive)
- ✅ Are all types explicit and correct? (Type Safety)
- ✅ Will this pass linting? (Zero Lint)
When to Load Additional Context
- Starting a new feature? → Read
yagni.mdfirst - Handling errors? → Read
no-defensive.md - Working with TypeScript? → Read
type-safety.md - Getting lint errors? → Read
zero-lint.md
Integration with Workflow
These principles should be applied:
- Before writing code - Plan with YAGNI in mind
- While writing code - Follow type safety and avoid defensive programming
- Before committing - Ensure zero lint violations
- During code review - Verify adherence to all principles
Philosophy
These principles exist to:
- Keep the codebase simple and maintainable
- Prevent technical debt accumulation
- Ensure high code quality
- Make the project easy to understand and modify
They may feel restrictive at first, but they lead to cleaner, more maintainable code.
Conflict Resolution
If principles seem to conflict:
- YAGNI takes precedence - simplicity wins
- Type safety is non-negotiable
- When in doubt, choose the simpler solution