45 lines
2.6 KiB
Markdown
45 lines
2.6 KiB
Markdown
---
|
|
type: convention
|
|
title: AI Agent Operating Rules
|
|
summary: 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?"
|
|
tags:
|
|
- type/convention
|
|
- domain/agent-orchestration
|
|
scope: global
|
|
last_updated: 2026-07-13
|
|
date: 2026-07-13
|
|
related:
|
|
- tdd-methodology
|
|
source: hyperthrive_dev
|
|
---
|
|
|
|
# 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
|