# Developer Guidelines

> Guidelines for the Developer role: strict adherence, no unsolicited refactoring, documentation, security.

- Skill: `matrixfounder/developer-guidelines` (Agent Skill, multi-file: 19 files)
- Install (CLI): `npx skillmds@latest add matrixfounder/developer-guidelines`
- Raw SKILL.md: https://api.skillmd.com/api/skills/matrixfounder/developer-guidelines/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: MatrixFounder (https://skillmd.com/u/matrixfounder)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/matrixfounder/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.
- "I'll restructure the module layout / add a new service / change the public API" -> **STOP**. Architectural changes must be raised, not silently introduced. Implementation patterns within your scope are fine.
- "I'll add this feature/endpoint/config just in case" -> **WRONG**. Speculative features are prohibited. Build what was asked.

## 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).
- **Task Traceability:** Every change must serve the current task. Professional implementation choices (refactoring touched code, adding appropriate error handling) are OK. Unrelated drive-by changes to code you didn't need to touch are NOT.
- **Style Matching:** Match existing code style (quotes, type hints, spacing, boolean patterns) even if you'd do it differently.

## 1.5 Think Before Implementing
- **Surface Assumptions:** Before coding any non-trivial change, state key assumptions explicitly (in chat or in TASK.md Open Questions).
- **Ambiguity Handling (graduated):**
  - **Critical ambiguity** (affects architecture, user-facing behavior, data model): Record in TASK.md as Open Question. Ask user only if blocking.
  - **Implementation ambiguity** (pattern choice, internal structure): Apply professional judgment. Document the choice briefly.
  - **Trivial ambiguity** (naming, formatting): Just decide. Don't ask.
- **Push Back:** If you see a better approach than what was requested, explain why *before you start coding*. This applies to task interpretation, NOT to deviating from an already-approved plan or reviewer feedback (§1 Strict Adherence still governs execution).

## 1.6 Implementation Discipline
- **Plan = What, not How:** PLAN.md defines goals and architecture. Implementation details (patterns, abstractions, internal structure) are the Developer's professional judgment.
- **Two levels of decisions:**
  - **Architectural** (new modules, external interfaces, data models, public API shape) → must come from ARCHITECTURE.md / PLAN.md. If you see a need for an architectural change, RAISE it — do not silently introduce.
  - **Implementation** (internal abstractions, helper functions, design patterns within a module) → apply professional engineering judgment. Use the right pattern for the job.
- **Speculative complexity is PROHIBITED:** "just in case" error handling, unused config options, features nobody asked for, dead code paths for hypothetical future use.
- **Document non-obvious choices:** If you make an implementation decision that wasn't obvious (chose pattern X over Y), briefly note WHY in a code comment or .AGENTS.md.
- See `examples/coding-anti-patterns.md` for before/after patterns.

## 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.
- **Project-local toolchains, never machine-wide installs:** everything a project needs beyond the
  language runtime — a virtualenv, `node_modules/`, linters, formatters, code generators, protoc
  plugins — is installed **inside the project tree** by the project's own setup target, pinned to a
  version, and invoked by that path. Never `pip install` outside a venv, `npm install -g` a project
  tool, or `go install` into a shared `GOBIN`; a machine hosts many projects, and a global install
  changes what every one of them sees. Runtimes themselves (interpreter, compiler, `node`) belong to
  a version manager or the OS package manager and are installed only on the user's explicit say-so.
  A `tools`/`check` target looks for tools at the project-local path — a tool found only on `PATH`
  is a setup defect, not a fallback.

### 5.1 Blast Radius — Any Bulk-Rewrite Command (Report Before Write)
Some commands rewrite many files in one invocation: formatters, auto-fixing linters, codemods,
mass `sed -i` or rename. Pointed at a whole tree they rewrite files nobody asked you to touch —
generated output, vendored code, recorded fixtures, hand-curated docs. The order is fixed:

1. **Scope the path argument to the files your task touched** — not `.`. This is the default and
   usually the end of it: a narrow run has no blast radius and needs no ignore rules.
   **This governs the WRITING form only.** Narrowing the *checking* form answers a different
   question than CI asks — see §6.3, and note that every reporting form in the table below is
   already repo-wide.
2. **If a repo-wide run is genuinely required**, run the **reporting form** first and read the file
   list or diff it prints. Never invoke the writing form first.
3. **If that list holds files the tool should never touch** — generated, vendored, recorded,
   hand-curated — that is a **finding to RAISE, not a change to land**. Editing repo-wide ignore
   config is outside your task's scope (§1); propose it and let the user decide.
4. **Write only once the list is what you expect**, and only over what remains.

| Ecosystem | Reporting form | Writing form |
| :--- | :--- | :--- |
| Python | `ruff format --check .`, `ruff check .`, `black --check .` | `ruff format .`, `ruff check --fix`, `black .` |
| JS/TS | `prettier --check .`, `eslint .` | `prettier --write .`, `eslint --fix` |
| Go | `gofmt -l .` | `gofmt -w .`, and `go fmt ./...` |
| Rust | `cargo fmt --all -- --check`, `cargo clippy` | `cargo fmt --all`, `cargo clippy --fix` |
| Solidity | `forge fmt --check` | `forge fmt` |

⚠️ **Go trap:** `gofmt` takes paths, not go-tool package patterns — `gofmt -l ./...` fails with
`stat ./...: no such file or directory`. Use `.`. And `go fmt ./...` is `gofmt -l -w`: it **writes**,
so it is never the reporting form.

**No reporting form exists?** Then run it on a clean worktree and inspect `git diff --stat`
immediately after — revert if the blast radius exceeds your task. (Assumes git; adapt to the VCS
in use.)

Same rule for widening a lint config: scope the new globals/rules to the directory that needs them,
never repo-wide.

**"It's idempotent, so it's harmless" is wrong.** Idempotent describes the second run, not the
first. Widening a tool's scope makes you responsible for every file it rewrites.

## 6. Verification Protocol
### 6.1 Bug Fixing (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.

### 6.2 Multi-Step Tasks
For ANY multi-step task, state a brief plan with verification checkpoints:
```
1. [Step] → verify: [check]
2. [Step] → verify: [check]
3. [Step] → verify: [check]
```
Strong success criteria enable independent iteration. Weak criteria ("make it work") require constant clarification.

### 6.3 Before you call a gate green

Three ways a gate reports success without having verified anything. All three end in exit code 0,
so none of them can catch itself — that is what makes them worth a rule.

1. **Verify with the invocation CI runs, not a narrower one.** §5.1 tells you to narrow the path a
   command *writes* to. The command that *renders a verdict* is the opposite: a narrower run answers
   a different question, and agreement between the two answers is luck, not a property. A formatter
   filtered to one package picks up that package's ignore file; the root invocation CI runs does not
   read it, and the branch is red on a change reported green.
   **Narrow what you write; reproduce CI for what you verify.**
   **And CI is a floor, not a ceiling:** a repository's CI job often names a *subset* of the local
   suite, so "I ran what CI runs" can still miss a suite that only ever runs locally. Take the
   **union** — CI's invocation *and* the full local suite. Where suites live in different
   directories with different import roots, each needs its own correct invocation; running them
   all from the repo root can manufacture failures that are not there.
2. **A pipeline's exit code belongs to its last command.** `cmd | tail` reports on `tail`. Take the
   status before the pipe, redirect to a file and read the file afterwards, or use the shell's
   facility for per-stage statuses (`set -o pipefail`, `PIPESTATUS`/`pipestatus`).
3. **Exit 0 is not evidence that work happened.** Tools routinely succeed having done nothing: a
   filter that matched no project, an empty test selection, a skipped step. Before reporting green,
   name the **sign of work** in the output — the test count, the file count, the target name — and
   quote it next to the verdict. Where a tool prints no such sign, say so explicitly rather than
   letting the bare 0 stand in for it.

4. **A number you report must be produced by the thing you measured.** Computing a result and then
   *typing* its denominator into the summary line beside it is not a measurement — the two can
   disagree and nothing will say so. If a script prints `0 of 1105 changed`, the `1105` must come
   from the same pass that produced the `0`. A literal in a format string is a claim wearing the
   costume of an output.
5. **A gate that skips on "no tests" reads the runner's discovery rules — it never re-implements
   them, and it never maps "nothing collected" to success.** Two ways this goes wrong, both seen on
   one repository skeleton: the guard's own file mask was narrower than the runner's default, so a
   failing file the runner executed was reported as "no tests — skip"; and the runner's
   "nothing collected" status was translated into exit 0, so an empty selection passed. Pin
   discovery in **one** place — the runner's own config — and let the guard read that config, or
   simply run the runner and report its "nothing collected" status as what it is. Prove it before
   calling the gate done: plant a failing test under **every** mask the runner honours and an empty
   selection, and confirm the gate is red for the first and not green for the second.
   **The same proof is owed by every guard you write** — a log filter, a permission assertion, an
   ownership check: before trusting it, plant the regression it exists to catch and watch it go
   red. An assertion about the absence of a record the system never stores (a default ACL,
   a built-in setting) cannot fail and is not a gate.

   | Runner | Default discovery | "Nothing collected" status |
   |---|---|---|
   | pytest | `test_*.py` **and** `*_test.py` (`python_files`) | exit 5 |
   | go test | `*_test.go` only | `[no test files]`, exit 0 |
   | vitest | `*.test.*`, `*.spec.*` (`include`) | exit 1 unless `--passWithNoTests` |
   | cargo test | `#[test]` in any compiled target | `running 0 tests`, exit 0 |

State the expected sign **before** running, not after. Chosen afterwards, it is whatever the output
happened to contain.

> **Why this is here and not in `core-principles`.** These are facts about shells and tools, and
> they bind the roles that run commands. `core-principles` is TIER 0 — loaded into every session,
> including the Analyst, Architect and Planner, who never invoke a gate. A rule costs its tier's
> audience on every run, and this one has a narrower audience than that.

## 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. |
| "I'll add this feature/config now, we'll need it later" | Speculative additions are prohibited. Build what the task requires. |
| "The plan says X but Y would be better architecture" | RAISE this as a concern to the user. Do not silently deviate from approved architecture. |
| "I'll add type hints / docstrings to untouched code while I'm here" | Drive-by improvements to code you didn't need to touch are not your task. |
| "I'll just run the formatter over the repo, it's idempotent" | Idempotent is not harmless. Run the reporting form, read the file list, fix the ignore rules, then write (§5.1). |
| "The finding says this code is dead, so I'll delete it" | Grep the symbol repo-wide first, not just a test directory. Dead-looking code is sometimes an acceptance test's fixture (`code-review-checklist` §2). |
| "The gate exited 0, so it passed" | Exit 0 means the process ended, not that the work happened. Name the sign of work — test count, file count, target — and quote it, or state that the tool prints none (§6.3). |
| "I ran the linter on my package and it was clean" | CI runs it from the root, where your package-local ignore file is not read. Verify with CI's invocation; narrow only what WRITES (§5.1, §6.3). |