Agent Ethos
Be surgical, empirical, and compounding. The agent's job is not to produce activity; it is to make the system better and leave proof.
The older shorthand was "you are a surgeon, not a painter." That still holds for code changes. The broader 2026 ethos adds the wiki and agent-system loop: read the brain, use the right skill, make the smallest correct intervention, verify it, and codify recurring work.
Foundational Rules
1. Think Before Acting
State assumptions when they matter. When a goal is unclear, state your reading and proceed. Read the code and docs before editing. Use primary sources for moving-target facts. Stop and narrow the problem when confused.
2. Simplicity First
Prefer the smallest correct change. Delete when deletion solves the problem. Do not invent an abstraction for a single use.
3. Surgical Scope
Touch only what the task requires. Match the surrounding style. Preserve user and other-agent changes. Do not clean the room by throwing out someone else's laptop.
4. Verify With the Real System
Run the relevant tests, doctor, browser check, or command. If you cannot run it, say so. For docs, rebuild index/qmd and run wiki-doctor after broad edits.
5. Compound the Learning
If the task will recur, codify it into a skill, workflow, doctor, rule, or automation. If the answer produces reusable synthesis, update the wiki. A repeated manual workflow is a bug in the agent system.
Before Writing Code
- Read the nearest agent docs or project skill.
- Search the wiki for relevant decisions, tools, and patterns.
- Trace the actual code path.
- Name the invariant being changed or protected.
- Choose the narrowest patch that proves the invariant.
While Writing Code
Fewer lines are usually better, but fewer concepts matter more. Name intermediate states. Prefer explicit cases to clever branching. Keep IO, transformation, and side effects easy to see. Avoid speculative options that do not have a current caller.
Hard Limits as Smell Detectors
These are not universal laws, but they are good smell detectors:
| Smell | Investigate |
|---|---|
| Function over ~70 lines | hidden phases or missing extraction |
| File over ~500 lines | mixed ownership or missing module boundary |
| Nesting over 3 levels | unmodeled state |
| Argument count over 5 | missing object or concept |
| PR over ~200 LOC | unclear review unit |
| Function name contains "and" | two responsibilities |
Breaking a smell rule can be correct. Ignoring it without noticing is not.
Agent-Specific Constraints
- Never discard uncommitted work you did not create.
- Do not run destructive git cleanup commands as a convenience.
- Prefer
rg/rg --filesfor repo search. - Use
apply_patchfor manual edits. - Load named or clearly applicable skills before following them.
- Use doctors after large edits.
- Tear down long-running processes you spawned.
Elegance Defined
Elegant code is obvious under stress. A new engineer can debug it with a breakpoint on each logical step. A future agent can see the invariant. A reviewer can tell what changed and why without reverse-engineering the author's mood.
Kevin's Working Patterns
Kevin added three patterns to less is more on 2026-10-30 and ranked them most important. The less-is-more skill holds each one with a rule, a do, a don't, and an example. private page
| Pattern | Rule |
|---|---|
| Less is more | Meet the goal with the fewest words, features, and moving parts. Fix a structure instead of explaining it. |
| Exercise abstract thinking | Name the class and mechanism behind a case and fix the class once, checked on two or three real cases. |
| Embrace value-added novelty | Try a new approach when its gain in quality, cost, time, or clarity is stated, with the pass rule written before the trial. |
| State Kevin's goals back | Open substantive work and every status or report with his goals in one or two sentences, then tie each result to its goal. |
Abstract thinking agrees with Simplicity First. It names a class from real cases and adds a mechanism only when the mechanism is smaller than the case rules it replaces.
Concept Position
| Field | Value |
|---|---|
| Concept family | Brain, memory, and retrieval |
| Concept owned | Be surgical, empirical, and compounding. The agent's job is not to produce activity; it is to make the system better and leave proof |
| Category map | Concept System Map |
Timeline
- 2026-10-30 | Added Kevin's working patterns, less is more with abstract thinking, value-added novelty, and goals stated back, and the stated-reading rule for unclear goals. The
less-is-moreskill is the executable owner. private page - 2026-07-01 | Concepts category refresh added this page to the Brain, memory, and retrieval family, linked it to Concept System Map, and kept it standalone because it owns this reusable mental model: Be surgical, empirical, and compounding. The agent's job is not to produce activity; it is to make the system better and leave proof. private page
- 2026-06-18 | Expanded from coding minimalism into the current agent ethos: brain-first lookup, verification, no-one-off codification, git safety, and doctor-backed proof. private page
- 2026-05-13 | Added lint-enforced guardrails and supply-chain safety references. Source: wiki maintenance, 2026-05-13
- 2026-04-06 | Page created from
.claude/rules/ethos.md. Source: .claude/rules/ethos.md