developer-guidelines

# 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](https://github.com/openai/skills/tree/main/skills/.curated/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. |