| --- |
| 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](https://lexi-lambda.github.io/blog/2019/11/05/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. |
|
|
