SecondBrain/convention/ai-agent-rules.md

45 lines
2.6 KiB
Markdown
Raw Normal View History

2026-07-13 18:36:59 +00:00
---
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
2026-07-13 20:39:01 +00:00
source: hyperthrive_dev/conventions/ai-rules.md
2026-07-13 18:36:59 +00:00
---
# 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