# ihumane · Code craft · v0.1 You are an agent about to write or change code that people will keep. This module is written for you, not for a human reader. It turns what experienced developers do by habit into rules you can follow and checks you can run. Read this file fully. Read the other files when the step below tells you to. --- ## Why this exists The classic books on clean code were written for people: people who forget what they wrote last month, get tired by the afternoon and avoid big changes because they're slow to make. You fail differently. You write fast, you don't get tired, and a 600-line diff costs you nothing. What you lack is the picture a person builds by living in a codebase: what already exists, what things are called here, what this team would never do. Without that picture you produce code that works today and costs someone tomorrow: 1. **It works, but it doesn't belong.** A second date helper beside the first, a class in a codebase of plain functions, a new name for an old thing. The next developer now has two ways of doing everything. 2. **It changes more than it should.** Reformatted files, renamed variables, improvements nobody asked for, old code left beside the new. The person reviewing it can't tell which lines matter. 3. **It says it works, but nobody checked.** Tests that mock away the thing they test, a test command that was never run, a report that says "done". The reader of your code is the next person: a developer on the team, the person you work for, or the next agent. Every rule here is about what they find when they open the file. --- ## Size the job first The full workflow is built for features and refactors. A one-line fix doesn't need all of it, and a heavy process on a small job annoys the person. | Size | Looks like | Do | |---|---|---| | **Small** | A bug fix, a change inside one function, a config tweak, a small script | Search for what exists (B1). Match the file you're in (B2). Make the smallest change (C1). Run the tests that exist and run `checks/tidy.js --diff`. Say what you ran and what you didn't (V1, V6). | | **Large** | A feature across several files, a new module or service, a refactor, a change to an interface other code depends on | The full workflow below, every step. Before writing, say your plan in a few lines: which files you'll touch and which existing pieces you'll reuse. | If unsure, treat it as small. Verifying is never skipped: it's where the person finds out whether to trust everything else you did. --- ## The workflow | Step | What you do | File | |------|-------------|------| | 1. Read first | Find what already exists, how things are named and done here, how the project runs and is tested, and where the ask ends. | `1-before.md` | | 2. Shape | Decide what things are called, where code goes, what each piece does and how it fails, before writing much. | `2-structure.md` | | 3. Change | Make the change: small, contained, safe, with nothing left behind. | `3-change.md` | | 4. Verify | Run it for real, test what it does, read your diff as the next developer, report what you checked and what you didn't. | `4-verify.md` | --- ## The format of every rule Rules in this module use the same fields: - **Rule:** what to do, as specifically as possible. - **Why:** what happens to a real person if you don't: the next developer, the reviewer, or the user. This lets you handle cases no rule covers. - **Agent trap:** the specific way agents like you get this wrong. - **Check:** how to verify it, ideally something you can run or count. Runnable checks live in `checks/`. Run them; don't trust your memory of what you changed. | Check | Finds | |---|---| | `checks/tidy.js` | Debug logs and `debugger` left in; `.only` and `.skip` in tests; empty catch blocks; likely secrets; TODOs; commented-out code; functions over 60 lines and files over 400. Node, no dependencies. `--diff` checks only the lines you changed. | --- ## Five rules that matter most If you remember nothing else: 1. **Search before you write.** The helper, the component or the type you're about to create probably exists. Use it. (`1-before.md` B1) 2. **Match the codebase, not your habits.** Its names, its patterns, its folders. Consistent beats clever. (`1-before.md` B2) 3. **Every line of the diff traces back to the ask.** Mention what else you noticed; don't change it. (`3-change.md` C1, C2) 4. **Run it before you say it works.** A claim with no command and no output behind it is a guess. (`4-verify.md` V1) 5. **Say what you didn't verify.** The gap they know about is a small task. The one they don't know about is a bug in production. (`4-verify.md` V6) --- ## Precedence The person's instructions and the project's own conventions come before this module. Match the codebase first: if it does something these rules advise against, follow the codebase in the code you write, and mention the conflict once in your report instead of changing it. A project's lint config, formatter, style guide, `CONTRIBUTING.md`, `AGENTS.md` or `CLAUDE.md` are part of its conventions. One exception: don't copy an unsafe pattern because it's already there (secrets in code, queries built from input: C8, C9). Write the safe version, point out the existing one, and let the person decide about it.