Skip to main content
Configure once, every model behaves the same way.
ai-assistant-instructions is the rules and conventions layer for every AI coding tool in the portfolio. The same files (CLAUDE.md, AGENTS.md, .cursorrules, etc.) are sourced from this repo so Claude Code, Gemini CLI, GitHub Copilot, and Codex all behave consistently.

​
What it does

  • Defines the canonical CLAUDE.md and AGENTS.md files used by every project
  • Sets the autonomous orchestration defaults — proceed on low-risk ambiguity, delegate context-heavy work, verify the result, and keep user output compact
  • Owns the model-routing policy — when to reach for Claude vs Gemini vs Copilot vs local MLX
  • Owns the tool-use rules — Read over cat, Edit over sed, Bash for shell-only
  • Owns AI-runtime concerns: skill execution semantics, subagent typing, Bifrost-routing details
  • Symlinks the canonical files into every consuming repo via Nix or a direnv hook
Cross-repo writing standards that humans also need to read — commit conventions, no-scripts, diagramming, CI/CD policy, OpenTofu check placement, Nix package placement, scrubbed values — live on this docs site. See Conventions for the full set. Situational agent guidance that once lived here as always-loaded rules — pre-commit architecture, the Nix tool policy, shared-workflow org references — now ships as on-demand skills in claude-code-plugins, keeping the per-session footprint focused on voice, tool use, skill-execution integrity, and repository-local routing. The default development loop is intentionally lightweight: gather enough context, choose the simplest verifiable path, implement the smallest correct change, and report only the result plus verification. PRD-heavy, test-first gating remains available for high-risk or explicitly gated work, but it is no longer the default for routine tasks.

​
The CLAUDE.md → @AGENTS.md convention

Every repo’s CLAUDE.md is a thin import of AGENTS.md in the same folder. Always. No exceptions. 
# AI Agents Configuration

@AGENTS.md
That’s the entire file. Two lines of content (plus a heading). All actual project guidance lives in AGENTS.md. Claude Code resolves @AGENTS.md as an inline file import (official docs) — the contents are loaded into context exactly as if they had been written into CLAUDE.md directly.

​
Why

Problem the convention solvesHow
Vendor lock-in. Claude reads CLAUDE.md, Codex / GitHub Copilot / Cursor / OpenAI agents read AGENTS.md, Gemini reads GEMINI.md. Duplicating content across them rots fast.One canonical file (AGENTS.md), every other tool’s config file imports it.
Context bloat. A 12 KB CLAUDE.md burns tokens on every session.CLAUDE.md becomes ~40 bytes; AGENTS.md carries the load and can still be split further via nested @path imports.
Size budgets. The shared _file-size workflow defaults to warn=6 KB, error=12 KB. A fat CLAUDE.md trips that gate.A 40-byte CLAUDE.md never trips it; AGENTS.md can opt into an extended: limit per repo via .file-size.yml when actually needed.
Single source of truth. Moving project rules between files in different vendors’ formats is an unforced error.All edits land in one file.

​
Where it applies

Every repo. Public or private, monorepo or single-purpose, infra or app. If a repo has a CLAUDE.md, it must be the two-line import. Project-level instructions, command runbooks, conventions, and tool guidance all belong in AGENTS.md (or files it @imports). The same convention applies symmetrically to GEMINI.md and any future vendor-specific files — each is a thin import of AGENTS.md. The one exception is ai-assistant-instructions itself. Its AGENTS.md is already auto-loaded globally on Nix-managed machines (the home-level ~/CLAUDE.md imports it), so a project-level @AGENTS.md import there would load the identical bytes twice in every session. That repo’s CLAUDE.md is a stub explaining exactly this, and its auto-loaded rules likewise come from the global ~/.claude/rules wiring rather than a per-repo .claude/rules symlink.

​
How to migrate a repo

  1. Move every section of the existing CLAUDE.md into AGENTS.md (merge with any existing content, dedupe, prefer linking to docs/*.md for deep dives).
  2. Replace CLAUDE.md with the two-line import shown above.
  3. If AGENTS.md ends up > 12 KB, either trim further (link out to docs/) or add a .file-size.yml extension: 
    # .file-size.yml — extends the shared default for AGENTS.md only
extended:
  limit: 32768
  files:
    - AGENTS
  4. Mirror the same change in any other agent file (e.g. GEMINI.md → @AGENTS.md).
  5. Update CI: most repos already inherit the _file-size check from JacobPEvans/.github. No per-repo workflow edit needed.

​
How it fits

Read byConsumed by
Claude Code, Gemini CLI, GitHub Copilot, CodexClaude Code plugins

​
Getting started

1

Clone or symlink

git clone https://github.com/JacobPEvans/ai-assistant-instructions ~/.ai-assistant-instructions and symlink the project files into the relevant repo, or import via the Nix module the README points to.
2

Pick a profile

Profiles cover personal, work, and learning contexts. The README enumerates which rules each one activates.
3

Update from upstream regularly

The rules evolve. Pull weekly or set up a routine in claude-code-routines.

Repo boundaries

How rules, plugins, and docs are split across three repos.

claude-code-plugins

Extends Claude Code with custom skills, hooks, and commands that respect these rules.

nix-ai

Packages the AI tools that read these rules.

AI pipeline

How rules + tools + automation become an actual development loop.

Source on GitHub

Rules, profiles, full README.