tomevault-io Developers Guidelines
0. Red Flags (Anti-Rationalization)
STOP and READ THIS if you are thinking:
- "This code is messy, I'll clean it up while I'm here" -> WRONG. You MUST change ONLY what the task requires.
- "I'll skip the test, it's a trivial change" -> WRONG. ALL changes require verification.
- "The reviewer didn't mention this, but I know better" -> WRONG. Fix ONLY what is requested in reviewer comments.
- "I don't need to update .AGENTS.md for such a small change" -> WRONG. Update
.AGENTS.mdfor touched source scopes under memory tracking policy.
1. Strict Adherence
- Follow Instructions: Execute the task EXACTLY as described.
- No Unsolicited Changes: NEVER refactor code or add features not explicitly requested.
- Scope Control: LEAVE unrelated code unchanged, even if it looks "bad" (unless it blocks your task).
2. Input Handling
- New Task: Read strict task description, project description, and code.
- Fixing Comments: Read reviewer comments and fix ONLY what is requested.
- Fixing Tests: Analyze report, fix bugs, ensures tests pass.
3. Anti-Loop Protocol
- Stop Condition: If tests fail 2 times with the same error, STOP.
- Analyze: Do not blindly retry. Analyze the error log, propose hypotheses, and record in
open_questions.md.
4. Documentation First
- Update .AGENTS.md: You are the Single Writer. Update existing
.AGENTS.mdin touched source scopes; create new ones only where project policy enables memory bootstrap.
5. Tooling Protocol
- Prefer Native Tools: ALWAYS use the IDE/agent's native tools (test runners, file operations, git integration) over raw shell commands.
- Shell as Fallback: Use shell commands ONLY when no native tool exists for the required operation.
- Verify Availability: Check which tools are available in the current environment before defaulting to shell.
6. Bug Fixing Protocol (Universal)
- Reproduce First: Never fix a bug without a failing test case that reproduces it.
- Verify Fail: Run the test to confirm it fails.
- Fix: Implement the fix.
- Verify Pass: Run the test to confirm it passes.
- Regression: Run the full suite to ensure no regressions.
7. Language Specific Guidelines
- Dynamic Loading: If you are working in a specific language, you MUST read the corresponding guideline file from
references/languages/if it exists.- Go:
references/languages/golang.md - Rust:
references/languages/rust.md - Solidity:
references/languages/solidity.md - Python:
references/languages/python.md - JavaScript/TypeScript:
references/languages/javascript.md
- Go:
- Application: Apply the specific rules in addition to the core guidelines above.
8. Security Quick-Reference
- Dynamic Loading: If the codebase uses a specific framework, you MUST read the corresponding security quick-reference from
references/security/if it exists.- Flask:
references/security/flask.md - Django:
references/security/django.md - FastAPI:
references/security/fastapi.md - Express:
references/security/express.md - Next.js:
references/security/nextjs.md(includes React-specific patterns; do NOT also load react.md) - React (standalone, no Next.js):
references/security/react.md - Vue.js:
references/security/vue.md - jQuery:
references/security/jquery.md - Vanilla JS/TS (frontend):
references/security/javascript-general.md - Go (net/http, Gin, Chi, Echo, Fiber):
references/security/golang.md - Solidity:
references/security/solidity.md - Rust:
references/security/rust.md
- Flask:
- Loading Rule: Load one framework-specific ref per file under review. Prefer the most specific match (e.g., Next.js over React, framework-specific over javascript-general).
- Application: Apply the LLM anti-patterns, grep patterns, and edge cases from the loaded reference to avoid common security mistakes during code generation and review.
- Source: Condensed from OpenAI security-best-practices skill.
9. Rationalization Table
| Agent Excuse | Reality / Counter-Argument |
|---|---|
| "It's a small change, no tests needed" | ALL changes require verification. A one-line fix can break the entire system. |
| "This code is bad, I'll refactor it" | You are NOT the architect. Fix ONLY what the task requires. |
| "The reviewer missed this issue, I'll fix it too" | Fix ONLY what the reviewer explicitly requested. Open a separate issue for new findings. |
| "I don't need to read the language guidelines, I know the language" | Language guidelines contain project-specific rules. ALWAYS load them. |
| "The security reference is too long, I'll skip it" | Security references exist to prevent YOUR mistakes. ALWAYS load them. |
Converted and distributed by TomeVault — claim your Tome and manage your conversions.