| name | golden-principles |
| description | The 10 agent-first operating principles governing how agents work in this repository. USE FOR: agent behavior rules, operating philosophy, principle lookup, governance invariants. DO NOT USE FOR: Azure infrastructure, code generation, troubleshooting, diagram creation. |
Golden Principles
These 10 principles govern how every agent operates in this repository.
They are adapted from the Harness Engineering philosophy for agent-driven
infrastructure development.
The 10 Principles
1. Repository Is the System of Record
All context must live in-repo, not in external docs or chat history.
If knowledge isn't committed to the repository, it doesn't exist for agents.
Agent outputs go to agent-output/, decisions go to ADRs, conventions go to
skills and instructions.
Test: Can a new agent session reconstruct full project context from repo files alone?
2. Map, Not Manual
Instructions point to deeper sources; never dump everything into context.
AGENTS.md is the table of contents. Skills hold deep knowledge. Instructions
enforce rules. No single file should try to be comprehensive.
Test: Does each context-loaded file stay under 200 lines? Does it point to
deeper sources rather than inline them?
3. Enforce Invariants, Not Implementations
Set strict boundaries but allow autonomous expression within them.
Enforce WHAT must be true (TLS 1.2, AVM-first, governance compliance),
not HOW to achieve it. Agents choose their implementation path within
the invariant envelope.
Test: Are rules expressed as constraints ("MUST use managed identity")
rather than scripts ("first create identity, then assign role...")?
4. Parse at Boundaries
Validate inputs and outputs at module edges, not in the middle.
Each workflow step validates its prerequisites exist and its outputs
conform to templates. Internal logic is the agent's domain.
Test: Does each agent check for required input artifacts before starting?
Does each output pass artifact template validation?
5. AVM-First, Security Baseline Always
Prefer Azure Verified Modules over hand-rolled Bicep.
Apply the security baseline (TLS 1.2, HTTPS-only, managed identity,
no public blob access) to every resource without exception.
These are non-negotiable invariants, not suggestions.
Test: Is every resource checked against AVM availability before coding?
Does every resource include the security baseline properties?
6. Golden Path Pattern
Prefer shared utilities over hand-rolled helpers.
Use the azure-defaults skill as the single source of truth for naming,
regions, tags, and service matrices. Use azure-artifacts templates as
the single source of truth for output structure. Don't reinvent.
Test: Are there duplicate conventions across agents? If yes, consolidate
into the appropriate skill.
7. Human Taste Gets Encoded
Review feedback becomes documentation, linter rules, or skill updates —
not ad-hoc fixes. When a reviewer catches a pattern issue, the fix is
to update the instruction or skill that should have prevented it.
Test: After receiving feedback, was the lesson encoded into a rule
(instruction, skill, or validator) rather than just applied once?
8. Context Is Scarce
Every token in the agent's context window must earn its keep.
Load skills progressively: golden-principles → azure-defaults →
task-specific skills. Don't load the full artifact template reference
when you only need one template. Use pointers over inline content.
Test: Does each agent load ≤ 5 instruction files? Are skills loaded
on-demand rather than all at once?
9. Progressive Disclosure
Start small, point to deeper docs when needed.
AGENTS.md gives the overview. Skills give deep knowledge.
Instructions give enforcement rules. Templates give exact structure.
Each layer adds detail when the agent needs it.
Test: Can an agent complete a basic task by reading only AGENTS.md
and one skill? Does it only load more when needed?
10. Mechanical Enforcement Over Documentation
If a rule can be a linter check, CI validation, or pre-commit hook,
make it one. Documentation is for humans; machines enforce rules.
The validate-artifacts.mjs script is more reliable than
a paragraph saying "use the correct H2 headings."
Test: For each documented rule, is there a corresponding validator
in scripts/ or package.json? If not, should there be?
How to Apply These Principles
For Agents
- Read this skill FIRST, before
azure-defaults
- Use the principles as a decision framework when uncertain
- When two approaches are equally valid, choose the one that better
aligns with these principles
For Contributors
- When adding a new instruction, check if it could be a linter rule instead (Principle 10)
- When adding content to an instruction, check if it exceeds 200 lines (Principle 2)
- When fixing a bug, encode the lesson into a rule (Principle 7)
For Code Review
- Does the change follow the golden path or create a new one? (Principle 6)
- Does it add context load or reduce it? (Principle 8)
- Does it enforce invariants or prescribe implementation? (Principle 3)
