make-code · diff
v0.4.0 to v0.5.0
60 added, 53 removed. Audit A to A.
---
name: make-code
description: >-
- Write application code. Use when implementing or fixing a feature, endpoint, or function; simplifying existing behavior; or speeding up a named hotspot (N+1, hot loop, extra I/O). Skip docs, agent instructions, Makefiles, and CSS-only restyles.
+ Write application code. Use when implementing or fixing a feature, endpoint, or function; simplifying existing behavior; or speeding up a slow path (N+1, hot loop, extra I/O). Skip when the task is documentation, an agent instruction file, a skill, a Makefile, a CSS-only restyle, or a review that does not ask for an edit.
metadata:
- version: 0.4.0
+ version: 0.5.0
author: "Diego Oliveira"
tags:
- code
- kiss
- dry
- yagni
- cyclomatic
- refactor
- performance
---
# Make code
- Think like a lazy senior developer. Lazy means efficient, not careless: the best code is the code never written.
+ Prefer the simplest, lightest, cheapest path that meets the request: less code, an existing tool, and no extra machinery. The Floor and the check still hold.
- Create application code under **KISS**, **DRY**, **YAGNI**, and **CC**. **KISS** is the path. **DRY** is one representation, earned. **YAGNI** is the stop. **CC** is the local ceiling.
+ Write or change application code. Each run picks one branch and keeps the Floor.
- Pick a **branch** and state it at the start of the run:
+ - New behavior (feature or fix) → **write**
+ - Same behavior, simpler, or faster on a named hotspot → **refactor**
- - new behavior (feature, fix) → **write**
- - same behavior, simpler → **refactor**
- - same behavior, faster → **refactor** with a named hotspot (see Tight performance)
+ ## Inputs
- ## Workflow
+ - `request` (text, required): the behavior to add, the bug to fix, the code to simplify, or the slow path to speed up. It comes from the user message.
+ - `codebase` (files, required): the project the change lands in. It comes from the workspace.
- 1. **Classify.** Branch from the request. A speed request needs a named hotspot (profile, N+1, accidental quadratic, extra I/O or alloc in a hot loop, or the user named it); none → **refactor**, or ask. **Done when:** the branch is named; a speed change cites the hotspot.
- 2. **Trace.** Name the problem and the entrypoints. Name the symbols you will change. Search every caller. Name the check that proves the change, and the convention source (nearest `AGENTS.md` / `CLAUDE.md` and one neighbor of the same kind, or `conventions: none`). Read existing docs. A bug is fixed at its shared root, not at the one caller the report names: fix the shared function once. Ask first: does this need building at all, or does something existing cover it? For a sensitive choice (architecture, contract, data, security), inform the user of each option and its consequences before building; for a small reversible choice, pick the simplest and state the assumption. **Done when:** the items that apply to this task are named (a bug needs callers; a feature needs entrypoints), or **YAGNI** stops the work.
- 3. **Climb.** Before new code, answer: does this already exist, does an existing method already do this job. Stop at the first rung that holds: (1) skip (2) in-repo helper (3) stdlib (4) platform (5) installed dependency (6) one line (7) minimum new code. A new dependency is the last resort, after rung 5 fails. **Done when:** the two answers are named and the chosen rung is named. A rung past (2) names the methods searched.
- 4. **Apply** the matching branch under Floor. **Done when:** that branch's criterion holds and **Comments** holds on the slice.
- 5. **Prove.** Smallest check of observable behavior that fails if the logic breaks. Mock only at the trust boundary (network, clock, filesystem, paid API). Call through real internals. Trivial one-liners need no test. A non-trivial change leaves one runnable check: a plain assert or self-check file. **Done when:** with observable behavior, **write** shows the check red before the slice and green after; **refactor** keeps the same check green; without observable behavior, the check fails when the logic breaks.
+ ## Steps
+ 1. **Classify.** Pick the branch from the list above. **Done when:** the run states `write` or `refactor`. A faster run names the hotspot (a profile, an N+1, an accidental quadratic, extra I/O or allocation in a hot loop, or the name the user gave). A faster run that cannot name it leaves this step unfinished and uses the Output exit.
+ 2. **Trace.** Fill the six fields. Search the workspace for every caller of each symbol the slice will change. A sensitive choice (architecture, contract, data, or security) names each option and its consequence, builds the simplest option that meets the request, and states that assumption. A small reversible choice states the assumption.
+
+ - `problem`: the defect or the behavior, in one sentence
+ - `entrypoints`: the paths the run will enter
+ - `symbols`: each symbol the slice will change. A bug names the function that owns the defect
+ - `callers`: every caller of those symbols, or `callers: none`. When workspace search is unavailable, shared symbols stay unedited and this field says the callers were not searched
+ - `check`: the check that proves the slice
+ - `convention`: the nearest `AGENTS.md` or `CLAUDE.md`, plus one neighbor of the same kind, or `conventions: none`. The doc that specifies this behavior, or `docs: none`
+
+ **Done when:** `problem`, `entrypoints`, `symbols`, `callers`, `check`, and `convention` are filled, or the run names an existing symbol that already covers the request and stops with no edit. A sensitive choice names the options, the option built, and the assumption.
+ 3. **Climb.** Before new code, answer whether this behavior already exists and whether an existing method already does this job. Stop at the first rung that holds: (1) skip (2) in-repo helper (3) stdlib (4) platform (5) installed dependency (6) one line (7) minimum new code. A new dependency is the last resort, after rung 5 fails. **Done when:** both answers and the chosen rung are named. Rung (2) names the helper. A rung past (2) names the methods searched. A new dependency names the rung 5 search that failed. Rung (1) adds no new code.
+ 4. **Apply** the matching branch under the Floor. **Done when:** that branch's criterion holds. KISS, CC, and Match hold on the slice. DRY, YAGNI, Comments, Blank lines, Intent over fewest, Tight performance, and Non-negotiables each hold, or the same line names that heading and why it is skipped.
+ 5. **Prove.** Run the smallest check of observable behavior that fails when the logic breaks. Use the project's test command when one exists (package script, Makefile, or the neighbor's test). Otherwise use a plain assert or a self-check file. Mock only at a trust boundary (network, clock, filesystem, or paid API). Call the real internals. **Done when:** `write` shows the check red before the slice and green after. `refactor` shows that same check green before the edit and after it, and when none existed the run adds one that passes before the edit. A trivial one-liner states why it has no check. When the check cannot run, the run reports `check: not run` and the reason.
+
+ ## Output
+
+ One line: `branch | rung | check`.
+
+ `branch` is `write` or `refactor`. `rung` is the Climb name. `check` is `red-then-green`, `stayed-green`, `none (<reason>)`, or `not run (<reason>)`.
+
+ When a corner cuts a real limit, add a line: `ceiling: <limit>; upgrade: <path>`.
+
+ When Trace stops because a symbol already covers the request, the line is `branch | skip | none (covered by <symbol>)`.
+
+ When `request` does not name the behavior or the code, ask once and make no edit until it does. When the run cannot ask, stop and name the missing request. When a speed request has no hotspot, ask once which limit to remove and make no edit until the user names it. When the run cannot ask, stop and name the missing hotspot.
+
## Branch write
- Do the *simplest thing* that could work. One slice.
+ One slice of new behavior.
- **Done when:** the requested behavior is observable; every new or rewritten function meets the **CC** cap; no type or file exists that this slice does not call.
+ **Done when:** the requested behavior is observable; every new or rewritten function is within the CC cap; every new type and every new file is called by this slice.
## Branch refactor
- Preserve behavior. Flatten with guard clauses before extract. Extract only with a responsibility name.
+ Preserve behavior. Flatten with guard clauses before an extract. Extract only under a responsibility name.
- **Done when:** behavior matches the original (proof from Prove); every touched function meets the **CC** cap; a reader of the Match neighbor is faster; every extract or inline obeys **Intent over fewest**; for a speed change, the named hotspot is gone and no new type exists solely to hold the old slower path.
+ **Done when:** the Prove check shows the same behavior as before the edit; every touched function is within the CC cap; each extract or inline keeps a name that carries the concept; a speed change removes the named hotspot and adds no type whose only job is to keep the old slower path.
## Floor (every branch)
- **KISS.** The *simplest thing* that could work. Essential path first. Types, files, knobs, and layers exist when this request uses them. Boring over clever. Fewest files. Same-size options: the edge-case-correct one. Deletion over addition. A smaller diff wins only once the problem is understood; a small change in the wrong place is a second bug.
+ **KISS.** The simplest, lightest, cheapest path that meets the request: less code, an existing tool, and no extra machinery. Essential path first. A type, a file, a knob, or a layer exists when this request uses it. Fewest files. When two options are the same size, pick the one that is correct on the edge. Deletion over addition. A smaller diff wins once the problem is understood.
- **DRY.** One authoritative representation per piece of knowledge. The second real duplicate earns extract; the first stays. Extract to a responsibility name. Copies that mean different things stay copies.
+ **DRY.** One authoritative representation per piece of knowledge. The second real duplicate earns an extract; the first stays. Extract to a responsibility name. Copies that mean different things stay copies.
- **YAGNI.** Build the need in this request. Add an abstraction only when a real caller needs it. The extra caller, provider, or flag arrives with its own request.
+ **YAGNI.** Build the need in this request. Add an abstraction only when a real caller in this request needs it. Another caller, provider, or flag waits for its own request.
- **CC.** Decision points + 1 (`if`, loops, `case`, `catch`, `??`, `||`, `&&`, `.?`, boolean short-circuit, ternary). `else` = 0. Cap **20** on new or rewritten functions unless the project sets another bar (`eslint complexity`, ruff `C901`, gocyclo, etc). Keep branches visible (guard clauses, named predicates). A linear validation chain or a flat `switch` is not a split trigger. Use the project's existing complexity command when one exists.
+ **CC.** Decision points + 1 (`if`, loops, `case`, `catch`, `??`, `||`, `&&`, `.?`, boolean short-circuit, ternary). `else` = 0. Cap **20** on new or rewritten functions unless the project sets another bar (`eslint complexity`, ruff `C901`, gocyclo, or the project's complexity command). A linear validation chain or a flat `switch` is not a split trigger. Use the project's complexity command when one exists; otherwise count with this definition.
- **Match.** The diff follows naming, errors, imports, and function shape from the convention source Trace named. Personal preference loses. `conventions: none`: follow the Floor and keep one style.
+ **Match.** The diff follows naming, errors, imports, and function shape from the convention source Trace named. The project's convention wins over a personal preference. `conventions: none`: follow the Floor and keep one style.
- **Comments.** Add a comment only when the code cannot say it. A function or class whose contract its name does not carry gets one short doc comment: the contract, the units, the errors, or the side effect. Form comes from a documented neighbor of the same kind; with no neighbor, the language standard (JSDoc, docstring, `///`, godoc), one line on purpose. A conditional comment states a constraint the name cannot carry. A fact that fits in an identifier is an identifier (`isRetryableStatus`) and needs no comment. Skip comments that restate the code, narrate steps, label sections, or record history; skip comments on obvious lines and on helpers whose name already states the contract. An inline callback is a named predicate (`items.filter(isRetryableStatus)`).
+ **Comments.** Put a fact in the identifier when it fits (`isRetryableStatus`). An inline callback is a named predicate (`items.filter(isRetryableStatus)`). A function or class whose name does not carry the contract gets one short doc comment: the contract, the units, the errors, or the side effect. Take the form from a documented neighbor of the same kind; with no neighbor, use the language standard (JSDoc, docstring, `///`, or godoc), one line on the purpose. A comment that stays states a constraint the name cannot carry. Leave out a comment that restates the line, narrates a step, labels a section, or records history.
- **Blank lines.** Same-kind declarations stay together. A blank line separates a declaration or assignment from a block (`if`, loop, `switch`, `try`, or a callback call such as `forEach`), a closed block from the code after it, and any statement from `return`/`throw`. `else`, `catch`, `finally`, a continued line, and the `}` that closes the current block stay attached.
+ **Blank lines.** Same-kind declarations stay together. A blank line separates a declaration or assignment from a following block (`if`, loop, `switch`, `try`) or callback call (`forEach`), and a closed block from the code after it. A `return` or `throw` that follows another statement in the same block has a blank line before it. A guard whose body is a diagnostic and a `return` or `throw` keeps those lines together. `else`, `catch`, `finally`, a continued line, and the `}` that closes the current block stay on the next line. An inline `if` that keeps the `return` on the same line keeps the blank line after it, but multiples of the same kind stay together.
```js
const trimmed = input.trim();
if (!trimmed) {
+ console.error('Empty input');
+
return '';
}
- if (/^https?:\/\//i.test(trimmed)) {
- return trimmed;
- }
+ const itsTrue = true;
- for (let index = 0; index < array.length; index++) {
- const element = array[index];
- }
+ if (itsTrue) return 'true';
- return `${DEFAULT_SCHEME}${trimmed}`;
- ```
+ const itsFalse = false;
- ```ts
- let hasValidItem = false
+ if (!itsFalse) return 'false';
items.forEach((item) => {
- hasValidItem ||= item.isValid
- })
-
- const container = document.querySelector<HTMLElement>(containerSelector)
-
- if (!container) {
- console.error('Container not found:', containerSelector)
- return
- }
-
- items = container.querySelectorAll<HTMLElement>(ITEM_SELECTOR)
+ seen.push(item.id);
+ });
- if (items.length === 0) {
- console.error('No items found.')
- return
- }
+ return trimmed;
```
- **Intent over fewest.** *Intent* outranks *fewest*. The one exception to **DRY**: a shared helper that hides the idea loses; keep the helper whose name still carries a concept. Split unrelated work. Fewer lines only when a reader of the Match neighbor is faster.
+ **Intent over fewest.** Intent outranks fewest lines. This is the exception to **DRY**: a shared helper that hides the idea loses to a helper whose name still carries a concept. Split unrelated work. Fewer lines stay when the result still matches the neighbor's shape and the name still carries the concept.
- **Tight performance.** Default is the cheap fast path: stdlib, one pass, no N+1, no accidental quadratic. Speed work runs only on a named hotspot, measured or named by the user. A cache, pool, or index waits for that measurement. Speculative optimization is **YAGNI**.
+ **Tight performance.** The default path uses the stdlib, one pass, no N+1, and no accidental quadratic. A cache, a pool, or an index waits for a named hotspot. Speculative optimization is **YAGNI**.
- **Non-negotiables.** Understanding before the diff. Validation and fail-closed at trust boundaries. Errors that prevent data loss. Secrets and authorization. Accessibility. Platform calibration (clocks, sensors). Anything the user named. A non-trivial change needs a check that fails when it breaks. An authorized corner that cuts a real limit: mark `ceiling: <limit>; upgrade: <path>`.
+ **Non-negotiables.** Validation and fail-closed at trust boundaries. Errors that prevent data loss. Secrets and authorization. Accessibility. Platform calibration (clocks, sensors). Anything the user named. An authorized corner that cuts a real limit is marked `ceiling: <limit>; upgrade: <path>`.