2.6 KiB
| type | title | summary | tags | scope | last_updated | date | related | source | |||
|---|---|---|---|---|---|---|---|---|---|---|---|
| convention | AI Agent Operating Rules | Baseline behavioral rules for AI agents operating in a role-based multi-agent workspace — role boundaries, mandatory test-after-change discipline, and architecture-change escalation. Answers "what is an agent allowed to do unsupervised?" |
|
global | 2026-07-13 | 2026-07-13 |
|
hyperthrive_dev/conventions/ai-rules.md |
AI Agent Operating Rules
Purpose
Governs the default boundaries an AI agent should respect when working inside a role-partitioned codebase/workspace, independent of any single project's specifics.
Core Principles
1. Act only within your assigned role, and read only what that role needs. Reading or acting outside an assigned layer (e.g. a developer agent editing architecture docs) is how role boundaries erode and unreviewed decisions slip in. Treat "not in my role" as a hard stop, not a judgment call to make silently.
2. Never infer context outside your layer — ask instead. An agent that fills gaps by guessing at another role's intent produces confident-looking but ungrounded work. When information needed to proceed correctly isn't available in-role, surface the uncertainty rather than assume.
3. Verify behavior after every change that could affect it, not just at the end of a task. "Assume code works" is the default failure mode for agents — run tests immediately after writing new code, refactoring, updating dependencies, or any change with behavioral surface, not only when the agent decides the task is "done."
4. Architecture changes always route through an explicit architecture step. Never let an agent restructure system boundaries as a side effect of a feature task. Document the decision (in whatever this project's architecture-decision system is) and update any affected top-level docs before proceeding.
Anti-Patterns
- Agent edits files or reads context outside its assigned role "because it seemed relevant" → role boundary violation; escalate instead
- Task marked done without running tests after the last change → unverified behavior, the single most common agent failure mode
- Silently making an architectural decision inside an unrelated task → skips review; route through the architecture-decision process explicitly
- Large, multi-concern PRs/diffs from an agent → harder to review and revert; keep changes small and single-purpose
Related
- tdd-methodology — the concrete test-isolation patterns this rule's "test after every change" discipline relies on