Universal vs. Specialized: The Definitive Guide to AI Agent Rule Architecture (Antigravity, Kiro, Claude Code, and OpenAI Codex)

📅 Created: 2026/11/03, Updated: 2026/11/03 ⏱️ Estimated reading time ~10 mins (1,963 words)

Architectural guide on AI agent rule engineering across Google Antigravity, Kiro, Claude Code, and OpenAI Codex. Covers universal AGENTS.md standards, token budgeting, YAML frontmatter lazy-loading, live file inclusion, and deterministic hook guardrails.

Table of Contents

Overview
1. Why AI Agent Rule Files Collapse: The 3 Core Anti-Patterns
2. 4-Agent Rule Engine Comparison: Universal vs. Specialized Features
3. Universal Best Practices Across All Agents
4. Scoping Architecture: What Belongs in Global vs. Workspace?
5. Exploiting Specialized Superpowers
6. The Production-Grade “Federated Rules Architecture”
1. Self-Audit Checklist
7. Conclusion
1. Download Production-Ready Multi-Agent Rules & Hooks

Overview

In my daily software engineering workflow, I orchestrate multiple AI coding agents side-by-side—Google Antigravity, Anthropic Claude Code, Kiro, and OpenAI Codex. Yet, the single most frustrating bottleneck I repeatedly encountered was “rule definition collapse and prompt drift across agent harnesses.”

Initially, I assumed that writing comprehensive coding guidelines and safety constraints into a single AGENTS.md or CLAUDE.md would allow every tool to behave intelligently. However, as my projects expanded into enterprise-scale multi-repo architectures, I ran into severe operational failure modes:

Duplication Drift : Copy-pasting identical guidelines into both AGENTS.md and CLAUDE.md , updating only one, and triggering endless style wars and broken PRs between agents.
Context Suffocation & Rule Neglect : Packing every possible convention into a monolithic 1,000-line markdown file, causing the LLM to skip critical instructions mid-session due to the Lost in the Middle phenomenon.
Plea-Based Security Failures : Politely pleading in markdown ( “Please never push directly to main” ), only to watch the agent casually execute git push origin main during tight context turns.
Hidden Tool-Specific Idiosyncrasies : Antigravity’s YAML frontmatter rules being completely ignored by other tools, Codex silently truncating instructions past 32 KiB, and Kiro’s dynamic file references failing to parse in Claude Code.

In this deep dive, I share the hard-won architectural patterns that resolved these pain points across all four major AI agents.

We will delineate what constitutes the Universal Foundation (open standards that apply everywhere) versus the Specialized Superpowers (vendor-specific extensions) , culminating in a robust, production-tested Federated Rules Architecture .

1. Why AI Agent Rule Files Collapse: The 3 Core Anti-Patterns

Engineers frequently stumble into three classic traps when authoring agent instructions.

Anti-Pattern 1: The Monolithic Context Tax

Attempting to document test conventions, commit message formats, deprecated library versions, and cloud IAM policies in a single root instruction file.

Because agents inject this entire document into the prompt window on every single tool call, a 1,000-line monolith drains your token budget and saturates the model’s attention mechanism, exponentially increasing instruction neglect.

Anti-Pattern 2: Duplication Drift

Maintaining separate CLAUDE.md and AGENTS.md files by manual copy-pasting. Inevitably, one gets updated while the other remains stale, leading to conflicting instructions and code regressions.

Anti-Pattern 3: Plea-Based Security

Relying solely on descriptive natural language text to prevent high-risk operations ( “Do not execute dangerous commands” ). Because LLMs are probabilistic, prompts get overridden during complex multi-step reasoning. Critical constraints must be mechanically enforced via hooks, permissions, or sandboxes—never polite prose.

2. 4-Agent Rule Engine Comparison: Universal vs. Specialized Features

Here is how the four major coding agents process and load operational rules:

Evaluation Dimension	Google Antigravity	Kiro (CLI / IDE)	Anthropic Claude Code	OpenAI Codex
Primary Rule Files	`~/.gemini/config/rules/*.md` `<repo>/AGENTS.md`	`~/.kiro/steering/.md` `.kiro/steering/.md` `AGENTS.md`	`CLAUDE.md` `~/.claude/rules/*.md` `AGENTS.md` (fallback)	`~/.codex/AGENTS.md` `<repo>/AGENTS.md` `AGENTS.override.md`
Open Standard `AGENTS.md` Support	Native (Always loaded)	Native (Always loaded)	Fallback (Used if no `CLAUDE.md` )	Native (Cascaded merge)
Document Size Limit	Model context window	Project dependent	Context window dependent	Default 32 KiB (Configurable in `config.toml` )
Conditional / Dynamic Loading	YAML Frontmatter ( `glob` , `model_decision` , `manual` )	Steering Config (Always, Conditional, Manual)	Hierarchy-based	`AGENTS.override.md` (Parent cutoff)
Dynamic Live File References	Via agent skills	`#[[file:...]]` Syntax (Supports line ranges & folders)	`@path/to/file` syntax	Inline text only
Execution Guardrails	PreToolUse / PostToolUse Hooks	Permission policies (allow/ask/deny)	PreToolUse Hooks ( `settings.json` )	`config.toml` Sandbox policies

3. Universal Best Practices Across All Agents

Regardless of which tool you use, three architectural principles remain universal:

1. The 3-Tier UNIX Cascade

Following /etc/ → ~/.config/ → ./ , agent instructions must cascade from broad to granular, where local workspace settings strictly override global configurations :

Global ( ~/.config/ , ~/.gemini/config/rules/ , ~/.claude/rules/ ) : Universal operator attribution, baseline security principles, default response language.
Workspace Root ( ./AGENTS.md ) : Core architectural constraints, mandatory build/test commands, repository structure.
Subdirectory ( ./src/api/AGENTS.md ) : Service-specific framework nuances and micro-architecture rules.

2. The 150-Line Context Budget

Target under 150--200 lines for root AGENTS.md files. Apply the litmus test to every sentence:
> “If I delete this line, will the agent make a catastrophic or unrecoverable error?”

Prune anything that linters, formatters, or typecheckers enforce automatically. Keep only non-obvious project idiosyncrasies and exact build commands.

3. Clear Separation: Rules vs. Skills

Never embed lengthy deployment runbooks or multi-step migration scripts inside rule files:
- Rules ( AGENTS.md ) : Invariant constraints, boundaries, and evaluation criteria.
- Skills ( SKILL.md ) / Runbooks : Operational step-by-step procedures loaded on-demand only when triggered.

4. Scoping Architecture: What Belongs in Global vs. Workspace?

Even when teams understand the 3-tier cascade, the most common engineering stumbling block is scoping boundary design : “Exactly which instructions belong in global user config, and which belong inside the repository?”

Confusing this boundary leads to disastrous cross-contamination—such as an agent accidentally deploying a personal test app to a corporate client’s AWS account, or leaking local Mac file paths into public GitHub CI builds.

Here is the production scoping boundary matrix I enforce across all enterprise agent workflows:

Scoping Boundary Matrix (Where to Define What)

Category	Global Scope ( `~/.config/` , `~/.gemini/...` )	Workspace Scope ( `./AGENTS.md` , `./.agents/...` )
Identity & Attribution	Operator Attribution & Persona ・Git commit author name & email ・Attribution policy (never attribute AI assistant names) ・Default conversational language (e.g. Japanese `です/ます` , English code comments)	Team & Project Context ・Internal product names and project naming conventions ・Assigned reviewers and stakeholder aliases
Engineering Principles	Universal Engineering Standards ・TDD mandate (Red-Green-Refactor, >=80% coverage) ・Immutability (return modified copies, zero mutation) ・Plan-first policy (align on design before edits) ・Function length limits (<50 lines)	Stack & Architecture Rules ・Directory structure conventions ( `features/` , `components/` ) ・State management & API client patterns (React Query, Zustand) ・Design system tokens and styling rules
Host Machine & OS Guardrails	Host Machine Safety Boundaries ・Non-intrusive GUI mandate (never hijack mouse/focus) ・Port collision prevention (dedicated 5-digit port ranges) ・Scratch files hygiene (strictly in `/tmp` , never repo root) ・Daemon/background process management	Build, Test & Dev Commands ・Exact build/test invocations ( `npm run build` , `pytest` ) ・Dev server startup commands ( `npm run dev` ) ・Linter & type-check commands ( `tsc --noEmit` , `ruff check` )
Security & Compliance	Universal Data Protection ・Zero hardcoded secrets (API keys, private tokens) ・Credential scanning & exfiltration prevention ・Network sandbox boundary enforcement	Domain Legal & Compliance Rules ・Industry regulations (e.g. FIEA prohibition on investment advisory) ・Monetization labeling ( `SPONSORED` / Ad disclosure) ・GDPR / HIPAA domain compliance requirements
Git & Release Strategy	Universal Git Protocols ・Conventional Commits format ( `feat:` , `fix:` ) ・HTTPS authentication enforcement (prevent SSH failures) ・Worktree isolation for concurrent branches	Repository Branch & Deploy Workflow ・Branch branching model ( `develop` integration → `main` prod) ・Hosting targets (Firebase Hosting, Cloudflare Pages, Cloud Run) ・GCP Project IDs, AWS profile names
Context Management	Session Budget & Delegation Policy ・Delegate heavy searches/build trials to subagents ・Compaction and session reset triggers	Inline References & Context ・Direct schema & type path pointers ( `#[[file:...]]` ) ・Location of key architectural codemaps and READMEs

The 3 Classic Scoping Violations in Production

When these boundaries blur, agents inevitably introduce subtle bugs and operational friction:

Violation 1: Global Leaking (Polluting Global Config with Workspace Assets)

Hardcoding project-specific identifiers—such as AWS_PROFILE=client-prod or absolute paths like /Users/user01/workspace/client-a/... —into global configuration files ( ~/.gemini/config/rules/ or ~/.claude/rules/ ).
When switching to a personal repository or a different client’s codebase, the agent unconsciously attempts to invoke client A’s credentials, causing permission failures or, worse, deploying code into the wrong infrastructure .

Violation 2: Workspace Leaking (Hardcoding Local Paths into Repositories)

Committing local machine paths ( file:///Users/kanji/... ), private SSH aliases, or personal credentials directly into a repository’s AGENTS.md .
The moment CI/CD (GitHub Actions), Docker containers, or Windows teammates pull the repository, automated pipelines immediately crash due to missing paths, while private machine configurations leak permanently into git history .

Violation 3: Global Bloating (The 10,000-Token Monolith)

Stuffing specialized best practices for every conceivable technology (Next.js, Python, Terraform, Docker, Go, Rust, Tailwind) into global rules because “they might come in handy.”
The agent gets loaded with 10,000+ tokens of irrelevant rules at the start of every session—even for a simple one-line shell script— choking its attention window and drastically increasing the likelihood of hallucination .

The UNIX Litmus Test for Rule Placement

Whenever you write a new rule, run it through these two quick tests:

“If I start a completely unrelated project tomorrow in another language for a different client, should this rule still apply 100%?”
- YES : Operator identity, TDD standards, GUI protection, secret leakage guards → Global ( ~/.config/ )
- NO : Framework specifics, build commands, cloud profiles, domain compliance → Workspace ( AGENTS.md )
“Can I publish this rule publicly on GitHub without redaction?”
- YES : Architecture patterns, lint commands, coding standards → Workspace ( AGENTS.md )
- NO : Internal credentials, private machine setup, proprietary account IDs → Global or Environment Variables

💡 The Middle Path: “Conditional Global Rules” via Frontmatter

When a rule applies across multiple projects but is only relevant during specific tasks (e.g. Terraform naming conventions), use Antigravity’s trigger: glob: "**/*.tf" or Kiro’s Conditional Steering. This stores the rule globally while injecting it into context only when matching files are actively opened .

5. Exploiting Specialized Superpowers

Once the universal foundation is in place, you can leverage vendor-specific features for maximum leverage.

Google Antigravity: Lazy-Loading via YAML Frontmatter

Antigravity’s standout capability is fine-grained frontmatter triggering in ~/.gemini/config/rules/*.md :

---
trigger: glob
globs: "**/*.tf, **/*.tfvars, infra/**/*.yaml"
description: Terraform naming conventions and provider requirements
---
# Infrastructure Rules
- Resource names must include environment prefixes (prd, stg, dev).

Using glob and model_decision , frontend coding tasks are never polluted by heavy infrastructure or migration rules.

Kiro: `#[[file:...]]` Live References & Steering

Kiro enables embedding dynamic file contents directly into steering documents without code duplication:

# API Response Contract
All error payloads must strictly comply with our central schema:
#[[file:src/types/api_errors.ts]]

When the underlying schema updates, the agent’s steering context automatically synchronizes. Furthermore, /context show allows real-time inspection of active context.

Anthropic Claude Code: The Symlink Trap & Universal File Ingestion ( @AGENTS.md )

When CLAUDE.md exists at the repository root, Claude Code prioritizes it over AGENTS.md .
While macOS and Linux engineers often resort to a quick local symlink ( CLAUDE.md -> AGENTS.md ), this introduces a catastrophic failure mode in multi-platform or enterprise team environments.

⚠️ The Windows “9-Byte Silent Deletion” Trap

On Windows machines, Git disables symlinks by default ( core.symlinks = false ).
When a Windows developer clones a repository containing a symlink, CLAUDE.md is materialized not as a valid link, but as a plain 9-byte text file containing the literal string "AGENTS.md" .
Claude Code silently ingests this 9-byte stub as the entire instruction set without throwing any warnings— effectively stripping every safety rule and architectural guideline in total silence.

✅ Cross-Platform Gold Standards

The Native @AGENTS.md Inclusion Syntax (Recommended)
Commit CLAUDE.md as a lightweight plain text file starting with an @ import directive:
```
@AGENTS.md

# Claude-Specific Directives
- (Append Claude-only behaviors or specialized subagent roles here)
```
Because it is standard markdown text, it works deterministically across Windows, macOS, Linux, and containerized CI runners.
Zero-Config Fallback (Omit CLAUDE.md Entirely)
Claude Code natively falls back to parsing AGENTS.md whenever CLAUDE.md is absent. If your project does not require Claude-specific prompts, keeping a solitary AGENTS.md file is the cleanest zero-maintenance pattern.

Additionally, enforce non-negotiable boundaries mechanically via deterministic PreToolUse hooks in .claude/settings.json rather than polite prose:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": ".*",
        "hooks": [
          {
            "type": "command",
            "command": "python3 scripts/secret_guard.py"
          }
        ]
      }
    ]
  }
}

Warning

Production Gotcha 1: Avoid the PreToolUse Hook “Self-Lockout Trap”
When scanning for secrets (e.g. OpenAI/Anthropic keys) in pre-tool execution hooks, using naive patterns without word boundaries (like sk-[A-Za-z0-9_-]+ ) will trigger false positives on kebab-case markdown text (e.g. risk-assessment-workflow... ). Exiting with code 2 on these false alarms causes Claude Code to block all subsequent tools —locking the agent in a loop where it cannot even read or edit files to fix the issue.
Always enforce strict word boundaries ( \b ) and ensure local development .env files and test mocks are safely bypassed in a fail-open design.

Tip

Production Gotcha 2: Guarding Against Overwrite Accidents ( install.py )
When distributing standardized rule packs across an engineering organization, manual cp commands frequently overwrite existing team members’ AGENTS.md or CLAUDE.md without warning. Using an automated installer script ( install.py ) that backs up existing rules to .bak before writing ensures smooth, conflict-free adoption.

OpenAI Codex: Clean Context Cuts with `AGENTS.override.md`

In large monorepos, Codex allows isolating sub-packages by placing AGENTS.override.md . This halts parent directory traversal, giving the agent a clean, uncluttered context slate. Note Codex’s 32 KiB default limit ( project_doc_max_bytes in config.toml ) to avoid silent truncation.

6. The Production-Grade “Federated Rules Architecture”

Here is the standardized repository layout I use to orchestrate all four agents without conflict:

my-project/
├── AGENTS.md                  # [SSOT] Universal core rules (< 200 lines)
├── CLAUDE.md                  # Claude-specific (@AGENTS.md import, 100% Windows-safe)
├── .kiro/
│   └── steering/              # Kiro-specific file-match rules & #[[file:...]]
├── .gemini/ (or global)
│   └── rules/                 # Antigravity glob & model_decision rules
├── .codex/
│   └── config.toml            # Codex byte limits & sandbox policies
└── .agents/
    └── hooks.json             # PreToolUse / PostToolUse deterministic guardrails

Self-Audit Checklist

Is root AGENTS.md under 200 lines?
Are global responsibilities (operator attribution, host machine guards) strictly decoupled from workspace stack definitions?
Are code style checks offloaded to linters and formatters?
Are CLAUDE.md and AGENTS.md decoupled from OS symlink traps via @AGENTS.md imports or native fallback?
Are destructive actions blocked by hooks rather than polite natural language?
Are long runbooks isolated into on-demand skills?

7. Conclusion

Managing AI agent guidelines has evolved beyond casually tossing reminders into a prompt box.

Strictly decouple Global and Workspace scopes (prevent credential and path leakage)
Anchor your foundation in a lean, vendor-neutral AGENTS.md
Enforce strict token budgets (< 150--200 lines) to avoid context saturation
Layer tool-specific superpowers (Antigravity’s frontmatter, Kiro’s dynamic inclusion, Claude Code’s hooks, Codex’s overrides)
Enforce critical safety invariants mechanically via deterministic hooks

By anchoring your setup in these 5 pillars, you eliminate agent regressions and prompt fatigue, unlocking a truly predictable, high-velocity multi-agent engineering workflow.

⏳ Coming Soon

Download Production-Ready Multi-Agent Rules & Hooks

Get the complete configuration pack featured in this article: universal AGENTS.md, deterministic hooks.json, Git safety guardrails, and validation scripts tested across Antigravity, Kiro, Claude Code, and Codex.

Get Starter Kit (Coming Soon) ※ Currently in preparation on Gumroad. The download link will become active upon launch.

🚀 Featured Products & Engineering Advisory (Cont-Aid LLC)

AI QUANT & MARKET PORTAL

Alpha Radar — Autonomous AI Quant & Market Intelligence

Powered by the frontier LLM orchestration and automated pipelines featured on this blog. Daily quantitative scoring, macro signals, and market analytics.

Explore Alpha Radar (Free)

AI & CLOUD ADVISORY

AI Agent Workflows & Cloud Architecture Consulting (Cont-Aid LLC)

Hands-on engineering advisory for AI coding agent standardization, hybrid LanceDB/SQLite memory hubs, and AWS / Google Cloud infrastructure modernization.

Contact & Inquiry