One repo, multiple AI agents: a tool-agnostic pattern for shared AI guidelines

Gabriele Mariotti — Sat, 11 Apr 2026 21:02:11 +0000

The problem

Every AI coding tool has its own way to receive project context:

Kiro → .kiro/steering/*.md
Claude Code → CLAUDE.md + .claude/rules/*.md
Cursor → .cursor/rules/*.md

If your team uses different tools — or if you want to switch without rewriting everything — you have a problem. You either:

Duplicate the same rules in every format → they diverge within days
Pick one tool and lock everyone in → someone is always excluded
Put rules in README and hope agents read it → they don't, reliably

None of these scale.

The pattern

Apply separation of concerns to AI agent configuration:

my-project/
├── ai/                          ← Knowledge (tool-agnostic, in git)
│   ├── README.md
│   └── terraform.md
├── .kiro/steering/              ← Kiro adapter (in git)
│   ├── ai-guidelines.md
│   └── use-terraform.md
├── .kiro/steering/local/        ← Kiro personal overrides (gitignored)
│   └── status.md
├── .claude/rules/               ← Claude adapter (in git)
│   └── tech-use-terraform.md
├── CLAUDE.md                    ← Claude shared instructions (in git)
└── CLAUDE.local.md              ← Claude personal overrides (gitignored)

Three layers:

Layer	Purpose	In git?
`ai/`	What to do (knowledge)	✅ Yes
`.kiro/steering/`, `.claude/rules/`	How to load it (adapters)	✅ Yes
`local/`, `CLAUDE.local.md`	Personal context (overrides)	❌ No

The knowledge layer: `ai/`

This is the single source of truth. Files here are:

Tool-agnostic — no references to Kiro, Claude, or any specific agent
Human-readable — standard markdown, useful even without an AI tool
Domain-focused — one file per topic (Terraform, security, API design, etc.)

Example — ai/terraform.md:

# Terraform — Steering rules

## Folder structure
Each folder is an independent Terraform root module...

## Standard files per module
Every module must contain: main.tf, variables.tf, outputs.tf, versions.tf, README.md...

## Security rules
### IAM — least privilege
- Scope resource ARNs to the specific project/environment — never "*" unless the API requires it...

No tool-specific syntax. No frontmatter. Just knowledge.

The adapter layer

Adapters are minimal files — 3-5 lines — that tell each tool when and where to load the knowledge.

Kiro adapter (`.kiro/steering/use-terraform.md`)

---
inclusion: fileMatch
fileMatchPattern: ["**/*.tf", "**/*.tfvars"]
---

# Terraform rules

Read and apply the rules in `ai/terraform.md` for all Terraform-related work.

Kiro loads this only when you're working on .tf files. The actual rules live in ai/terraform.md.

Claude adapter (`.claude/rules/tech-use-terraform.md`)

---
globs: ["**/*.tf", "**/*.tfvars"]
---

# Terraform Rules

Read and follow the guidelines in `ai/terraform.md` before doing any Terraform work.

Same concept, different syntax. Both point to the same source.

Meta-adapter: teaching agents the pattern

One file tells each agent how the system works:

Kiro (.kiro/steering/ai-guidelines.md):

---
inclusion: always
---

# AI Guidelines Convention

Technical guidelines are in `ai/` — tool-agnostic, single source of truth.

## Structure
- `ai/<topic>.md` ← domain knowledge
- `.kiro/steering/` ← Kiro adapters (in git)
- `.kiro/steering/local/` ← personal overrides (gitignored)

When updating a guideline, modify only `ai/<topic>.md`.

Claude (CLAUDE.md):

# My Project

## AI Guidelines Convention
Technical guidelines are in `ai/` — tool-agnostic, single source of truth.
Adapters in `.kiro/steering/` (Kiro) and `.claude/rules/` (Claude Code).
Personal overrides: `.kiro/steering/local/` and `CLAUDE.local.md` — not in git.

When updating a guideline, modify only `ai/<topic>.md`.

The personal layer

Some context is personal or sensitive:

Project status and TODOs
Credentials and environment config
Personal preferences and workflow notes

This goes in tool-specific locations that are gitignored:

Tool	Personal location	Gitignore rule
Kiro	`.kiro/steering/local/`	`.kiro/steering/local/`
Claude	`CLAUDE.local.md`	`CLAUDE.local.md`

The `.gitignore`

# Kiro
.kiro/*
!.kiro/steering/
.kiro/steering/local/

# Claude
CLAUDE.local.md

This tracks .kiro/steering/ (adapters) but ignores .kiro/steering/local/ (personal).

Why this works

Single source of truth

Change ai/terraform.md once → every agent picks it up. No drift, no sync issues.

No vendor lock-in

Switch from Kiro to Claude? The knowledge stays. Add Cursor tomorrow? Write a 3-line adapter.

Team-friendly

Everyone sees the same rules
New team member clones the repo → gets all the knowledge immediately
Personal overrides don't pollute the shared config

Progressive adoption

Start with one file in ai/. Add adapters as needed. The pattern scales from 1 file to 50.

Human-readable

ai/ is just markdown. No frontmatter, no tool syntax. A developer without any AI tool can read it and follow the same conventions.

Adding a new domain

Create ai/new-topic.md with the rules
Create adapter for each tool:
- .kiro/steering/use-new-topic.md (with appropriate inclusion mode)
- .claude/rules/tech-use-new-topic.md (with appropriate globs)
Commit all three files

Time: 2 minutes. The knowledge is written once, loaded everywhere.

Conclusion

The insight is simple: knowledge and configuration are different concerns. Knowledge is what your project needs. Configuration is how a specific tool loads it.

Separate them, and you get:

One place to maintain rules
Freedom to use any AI tool
Clean git history (knowledge changes are meaningful, adapter changes are rare)
Team alignment without tool alignment

The ai/ folder is your project's brain. The adapters are just plugs.

DEV Community: Gabriele Mariotti