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

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.