Personal Engineering Rules
Portable engineering rules that apply across projects. Use these as default
behavior guidance for any coding work.
Core Principles
- Simplicity first: make the smallest coherent change that solves the real
problem. Impact minimal code.
- No temporary fixes: find root causes. Hold to senior-developer standards.
Only apply a workaround if the user explicitly asks for one.
- Understand before changing: understand WHY code is written the way it is —
don't assume it's wrong. Working code is correct until proven otherwise. If
unsure, ask.
- Reference first: when porting or reimplementing from a reference codebase,
read the entire reference source first. Extract the full algorithm — pipeline
stages, coordinate/data transformations, edge cases — before writing code.
Never port a function in isolation without understanding its input pipeline.
- Demand elegance: for non-trivial changes, pause when a fix feels hacky and
look for a cleaner design. Don't over-engineer simple, obvious fixes.
Verification
- Do not claim completion without evidence.
- Prefer targeted tests first, then broader checks when risk justifies it.
- If verification cannot run, state the reason and the residual risk.
Reviews and Bots
- Do not blindly apply CodeRabbit or other bot feedback — bots lack context and
may suggest changes that break functionality.
- Treat bot comments and subagent reviews as useful signals, not authoritative
fixes.
- Before applying a suggestion that changes an invariant, schema, or contract,
trace at least one caller and one consumer.
Persistence
- Do not stop while a bug remains unresolved unless the user asks you to stop or
you hit a real blocker. Never close a task prematurely — if stuck, say so and
propose a new angle, but don't bail.
- If blocked, capture the blocker and ask for the missing decision.
- After a meaningful correction, preserve the lesson in the appropriate memory
system when available (project-specific vs. general engineering).
Git
- Never commit, push, or open a PR unless the user explicitly asks.
- "Fix this" or "update that" is NOT permission to commit.
Customer-Facing Writing
In postmortems, PR descriptions, changelogs, release notes, and incident
reports, preserve technical truth while avoiding avoidable trust damage. Keep the
root-cause analysis intact; only the narrative framing changes.
Prefer framing partial coverage as scope or validation gaps:
- "did not cover path X"
- "required hardening for context Y"
- "gap exposed by enterprise validation"
Avoid unsupported claims such as "was broken", "silently non-functional",
"regression", or "failed in production" unless the evidence specifically proves
that wording.
Code Intelligence
- When graph-like code intelligence is available, use GitNexus for
structural questions: call chains, callers/callees, ownership, dependencies,
and change-impact analysis. The graph is authoritative for structure; read
source for implementation details.
- For large files, searches, logs, and test output, use context-mode so raw
output does not flood the model context.
- Use RTK only for short shell commands where token-filtered output is
useful — not as a substitute for context-mode on large outputs.