Monorepo AI Rules

A reference monorepo showing how to structure AI agent instructions across a real multi-stack codebase. No backend implementation — only the structural and instructional files that govern how agents work.

Companion to the article Convenience always wins over nostalgia.

---

What this is

AI agents do not replace engineering judgment. They automate repetitive execution, enforce decisions, and help experienced engineers work across large codebases without wasting attention on mechanical tasks. The missing piece in most agent setups is not a better prompt — it is a structured system of rules that travels with the repository and constrains agent behavior in every session.

This repository demonstrates that system applied to a real monorepo: a Next.js web app, a Go API, a Rust identity service, a Python AI layer, an iOS app, and an Android app. Every service and app has its own AGENTS.md and .agents/rules/ directory. Cross-cutting rules live at the root. Claude Code skills provide executable workflows for the recurring gates every engineer runs before shipping.

Use it to understand the approach and adapt it to your own projects.

The rules system

Rules live in two places:

Root-level rules (/.agents/rules/) apply across the entire monorepo regardless of language or framework. They cover agent behavior, git and branching, security, naming, constants, abstractions, control flow, identifiers, persistence, migrations, transactions, query design, dependency audit, the LLM data boundary, and how executable plans must be written.

Per-project rules (e.g. services/api/.agents/rules/) apply only within that service or app. They cover architecture, approved dependencies, testing conventions, error handling, and anything specific to that stack — Go, Rust, Python, Swift, Kotlin, or Next.js.

The root AGENTS.md is the index. It tells an agent which rules exist, what they cover, and where to find them. Each project-level AGENTS.md does the same for its subtree.

The skills

.claude/skills/ contains five executable Claude Code skills:

Repository layout

.
├── AGENTS.md                        # Root index — read this first
├── CLAUDE.md                        # Claude Code pointer to AGENTS.md
├── .agents/rules/                   # Universal rules (all stacks)
├── .claude/skills/                  # Executable Claude Code skills
├── apps/
│   ├── web/                         # Next.js (Bun workspace, RSC-first)
│   ├── mobile-ios/                  # Swift / SwiftUI
│   └── mobile-android/              # Kotlin / Jetpack Compose
├── services/
│   ├── api/                         # Go — business API + MCP server
│   ├── identity/                    # Rust — authentication service
│   └── ai/                          # Python — LangGraph agentic layer
├── docker/                          # Compose files (infra_dev / infra_test)
├── docs/                            # Architecture, process, and product docs
└── tools/                           # Shared tooling

Each apps/* and services/* directory contains its own AGENTS.md, CLAUDE.md, and .agents/rules/ subtree.

How to use it

Read AGENTS.md at the root, then explore the per-project instruction files for the stack you care about most. The rules are not boilerplate — they encode specific decisions about architecture, approved dependencies, security boundaries, and test strategy.

Do not copy rules you do not understand. Rules that describe an architecture you have not chosen, a library you are not using, or a constraint that does not apply to your context will produce code that looks correct but is not. Adapt the structure; rewrite the content for your own project's decisions.

The article explains the reasoning behind this setup in full.