title: Core Beliefs
description: Agent-first operating principles for the sql-env project
type: explanation
doc_type: explanation
Core Beliefs
Agent-first operating principles for this project.
Philosophy
"Humans steer. Agents execute."
When something fails, the fix is never "try harder" — it's "what capability is missing?"
Principles
1. Repository Knowledge is the System of Record
Anything an agent can't access in-context effectively doesn't exist. Knowledge that lives in Slack, Google Docs, or people's heads is invisible to the system.
Implication: Push context into the repo. Design decisions, product principles, and team conventions must be documented in versioned files.
2. Enforce Invariants, Not Implementations
Mechanical constraints (lints, tests, type systems) apply everywhere at once. Narrative instructions degrade with context length.
Implication: When possible, encode rules as code (lints, schemas, types) rather than prose (AGENTS.md instructions).
3. Design Before Implementation
Think about interfaces before implementation details. The spec-first workflow (Research — Sketch — Spec — Verify) produces deeper, more coherent modules than "prompt and iterate."
Implication: Use the autocode pipeline. Don't skip the research phase.
4. Parse, Don't Validate
Prefer parsing data into precise types early rather than validating ad-hoc throughout the codebase. Invalid states should be unrepresentable.
Reference: Parse, Don't Validate
5. Boring Technology is Agent-Friendly
Technologies with stable APIs, composability, and strong training-set representation are easier for agents to model.
Implication: Prefer well-established libraries over cutting-edge. Sometimes it's cheaper to reimplement a subset than to work around opaque behavior.
6. Taste is Captured Once, Enforced Continuously
Human taste is fed back into the system through review comments, refactoring PRs, and bug fixes. Once captured, it applies to every future line of code.
Implication: Use the compound-engineer to extract learnings. Update lints when patterns emerge.
Anti-Patterns
- Encyclopedia AGENTS.md: When everything is "important," nothing is.
- Shotgun Parsing: Validation scattered throughout the codebase instead of at boundaries.
- Try Harder Debugging: Prompting differently instead of fixing the environment.
- AI Slop Fridays: Manual cleanup sessions instead of continuous garbage collection.