# Keep your AGENTS.md in sync -- One Source of Truth for AI Instructions

DevFeed: [Keep your AGENTS.md in sync -- One Source of Truth for AI Instructions](<https://devfeed.tech/articles/keep-your-agents-md-in-sync-one-source-of-truth-for-ai-instructions-25211.md>)

Original publisher: [Read original article](<https://kau.sh/blog/agents-md/>)

Author: Kaushik Gopal

Published: 2025-07-03T22:22:12Z

Content type: tutorial

Language: en

Sources: [Kaushik Gopal's Site](<https://devfeed.tech/sources/kaushik-gopal-s-site.md>)

Topics: [AI Development](<https://devfeed.tech/topics/ai-development.md>), [Development](<https://devfeed.tech/topics/development.md>), [Tool](<https://devfeed.tech/topics/tool.md>)

Tags: [ai-development](<https://devfeed.tech/tags/ai-development.md>), [codex](<https://devfeed.tech/tags/codex.md>), [developers](<https://devfeed.tech/tags/developers.md>), [maintenance](<https://devfeed.tech/tags/maintenance.md>), [make](<https://devfeed.tech/tags/make.md>), [opencode](<https://devfeed.tech/tags/opencode.md>)

## AI overview

This post describes organizing AI assistant instructions in a single source-of-truth repository. It separates user-level defaults from project-level rules and uses symlinks and a Makefile setup command to share configuration across Claude, Codex, and OpenCode.

## Source excerpt

Getting useful results from your AI assistant often comes down to the instructions you give it. Most developers treat that step casually, then wonder why the output is mediocre. One of the simplest ways1 to improve this is to keep one set of master instructions in an AGENTS.md file. In it, you define persistent rules that shape every interaction with the agent. Writing those instructions once is easy enough. Keeping them in sync is the annoying part. If you use more than one tool, things drift fast. So I keep one repo as the source of truth for my AI setup, then wire my tools and projects back to it. This post is the simple version of that setup. Good news Most coding tools have since consolidated around AGENTS.md as the standard. That makes this much simpler than it used to be. I talked about this topic in detail on my AI development podcast: How I organize my AI instructions # I keep my setup at two levels: User-level instructions: my personal defaults that I want available everywhere Project-level instructions: the rules and context that only apply to one repo User level: one source of truth ## I keep my shared AI setup in a single repo. That repo holds the things I want to maintain in one place: AGENTS.md reusable skills/ reusable commands/ compatibility shims like CLAUDE.md Then I wire my local tools back to that repo with one command from the repo's Makefile: make setup That command creates the symlinks for me. I am not updating the same instructions by hand for Claude, Codex, and OpenCode. I edit the shared files once in my repo, and the tools point back to them. At the user level, I keep it direct. The repo is the source of truth, so the tool-specific paths symlink straight to it. For example: ~/.claude/agents -> ~/my-local-directory/aikado/agents ~/.config/opencode/agents -> ~/my-local-directory/aikado/agents So the maintenance story is simple: keep shared defaults in one repo symlink tools back to that repo edit once Project level: thin local scaffolding #