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.md for 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.md in 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)

1. Reproduce First: Never fix a bug without a failing test case that reproduces it.
2. Verify Fail: Run the test to confirm it fails.
3. Fix: Implement the fix.
4. Verify Pass: Run the test to confirm it passes.
5. 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
• 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
• 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