principles

name	principles
description	Always-on operating principles for coding agents. Every coding agent working in this environment must read this before designing, implementing, reviewing, or debugging changes, then follow the roadmap to the one reference that matches the task. Applies to all code and repository work.

Principles

Build verifiable changes. Code is the medium; durable value lives in intent, boundaries, artifacts, and evidence.

Core loop

Before changing code:

1. Name the observable done state: test, command output, screenshot, API response, log, metric, or review checklist.
2. Read the nearest existing implementation before inventing a new path.
3. Identify the data flow, canonical owner, compatibility boundary, and risk boundary.
4. Choose the smallest coherent change that preserves the contract.
5. Verify on the closest real path practical for the risk level.
6. Report evidence and remaining risk.

Principles

1. Observable done beats intention. A task is done when an artifact proves it.
2. Existing path before new path. Reuse local helpers, types, tests, and naming before adding surface.
3. Data shape before control flow. A better carrier object or source of truth removes branches. Parse and validate at boundaries; never build on guessed shapes.
4. Every branch is surface area. Add fallback, config, flag, or API surface only for a real supported state or caller. Missing dependencies fail clearly instead of silently degrading.
5. Carrier data is complete and boring. Construct complete, immutable values at boundaries; keep mutation local to runtime accumulators.
6. Raw artifacts before summaries. Persist durable raw artifacts; derive reports and metrics later.
7. Debug by falsifiable hypothesis, then fix the root cause.
8. Gate irreversible risk with preview, verification, audit trail, and rollback path.
9. The repository is the system of record. Context that lives only in chat, external docs, or someone's head is invisible to the next agent and the next hire. Land decisions, plans, and constraints in the repo.
10. Tend the harness, not just the change. You are responsible for the environment you work in. When you struggle, hit a recurring problem, or find missing context, that is a defect in the harness: fix the root cause, then add the check, tool, or doc that makes the next occurrence either caught mechanically (lint, test, CI, error message that teaches the fix) or arrive with the context needed to solve it. Prefer mechanical enforcement over prose rules.

Roadmap

This file is a map, not a manual. Read the one reference that matches the task; skip the rest.

• Designing, planning, or implementing a change → references/writing-code.md
• Reviewing code, a diff, or a PR → references/code-review.md
• Debugging, flaky tests, regressions, incidents → references/debugging.md
• The user stated a durable, generalizable principle worth keeping → references/upstreaming.md

Reporting

For implementation work, end with: changed files, verification run, compatibility impact, remaining risk. For tiny changes, one concise paragraph is enough.