{"slug": "what-a-good-agents-md-should-teach-an-agent-on-day-one", "title": "What a good Agents.md should teach an agent on day one", "summary": "The Agentic AI Foundation, hosted by the Linux Foundation, has standardized AGENTS.md as a plain Markdown file for instructing coding agents in repositories. A developer's experience highlights that effective agent behavior comes from a structured stack of durable instructions, including root AGENTS.md, SOUL.md, USER.md, and TOOLS.md, which define boot order, working posture, and red lines. The key is separating judgment rules from repo-specific mechanics to avoid a 'junk drawer' effect.", "body_md": "I hit this last week while working inside my own OpenClaw workspace: the agent had access to the right files, the right tools, and the right project context, but the useful behavior didn't come from any one magic prompt. It came from a small stack of durable instructions.\n\nThe root `AGENTS.md`\n\nsaid what to read first. `SOUL.md`\n\ndefined the assistant's operating posture. `USER.md`\n\ngave personal context. `TOOLS.md`\n\nseparated reusable tool behavior from local machine details. Skill docs explained when to load specialized workflows.\n\nThat structure has proven useful for me time and time again.\n\nAGENTS.md, now part of the [Agentic AI Foundation](https://aaif.io) ecosystem hosted by the Linux Foundation, gives developers a plain Markdown place to tell coding agents how to work in a repo. The format is intentionally simple. The hard part isn't the file. The hard part is deciding what deserves to live in it.\n\nA good `AGENTS.md`\n\nshould answer one question first: what should the agent do before touching code?\n\nIn my workspace, the startup path is explicit:\n\n`SOUL.md`\n\n`USER.md`\n\n`MEMORY.md`\n\nThat gives the agent a boot order. It doesn't need to guess which file matters, whether memory is allowed, or whether private context belongs in a shared chat.\n\nMost repo instructions skip this. They say \"follow project conventions\" and then bury the conventions across a README, package scripts, CI config, old PRs, and comments. An agent can search, but search isn't the same as orientation.\n\nGive it a first route through the repo.\n\nYour repo probably doesn't need a `SOUL.md`\n\n, but the pattern is useful. One file can define working posture, while `AGENTS.md`\n\ndefines project behavior.\n\nFor a software repo, that might look like this:\n\n```\n## Working posture\n\n- Read the existing code before proposing new abstractions.\n- Prefer local helpers over new dependencies.\n- Keep changes scoped to the user request.\n- Run the narrowest useful test first, then broaden if the change touches shared behavior.\n```\n\nThose are judgment rules. They belong near the top because they shape every later decision.\n\nThen put repo-specific mechanics somewhere else:\n\n```\n## Commands\n\n- Install dependencies: `pnpm install`\n- Run unit tests: `pnpm test`\n- Run type checks: `pnpm typecheck`\n```\n\nWhy split them? Because commands change faster than principles. If you mix everything together, the file turns into a junk drawer. Agents will still read it, but you won't know which instruction is steering behavior.\n\nThe best line in my workspace `AGENTS.md`\n\nis short: `trash > rm`\n\n.\n\nThat teaches a local safety rule in three tokens. It says destructive deletion should be recoverable. It doesn't explain Unix philosophy. It doesn't lecture. It gives the agent a rule it can apply while acting.\n\nYour `AGENTS.md`\n\nshould include boundaries like that:\n\n```\n## Red lines\n\n- Don't edit generated files directly.\n- Don't change public API behavior without updating tests.\n- Don't run migrations against shared databases.\n- Use `trash` instead of `rm` when deleting local files.\n```\n\nNotice the shape: concrete verbs, concrete objects, concrete limits.\n\n\"Be careful with data\" is too vague. \"Don't run migrations against shared databases\" gives the agent something it can obey.\n\nAgents often fail by reading too little or too much. Repo instructions can fix both.\n\nIn my workspace, `MEMORY.md`\n\nis only loaded in main sessions, not shared contexts. That's a privacy rule and a context rule at the same time. Daily notes are raw logs. Long-term memory is curated. `TOOLS.md`\n\nis for environment-specific notes, while skills are reusable.\n\nThat structure avoids a common problem: durable instructions become a dumping ground for every fact anyone might need someday.\n\nFor a team repo, you can use the same split:\n\n```\n## Context files\n\n- `README.md`: human setup and project overview.\n- `AGENTS.md`: agent workflow and repo norms.\n- `docs/architecture.md`: current service boundaries.\n- `docs/runbooks/`: production procedures. Read only when the task touches operations.\n- `.env.example`: allowed environment variable names. Never read real `.env` files unless asked.\n```\n\nThat last sentence matters. It tells the agent where the map ends.\n\n`TOOLS.md`\n\nin my workspace makes a clean distinction: skills define how tools work, and `TOOLS.md`\n\nstores local specifics like camera names, SSH aliases, speakers, or preferred voices.\n\nThat maps well to engineering teams.\n\nA reusable instruction might say:\n\n```\nWhen debugging CI, inspect the failing job logs before changing code.\n```\n\nA local instruction might say:\n\n```\nThe staging dashboard is at <internal URL>.\n```\n\nThose shouldn't live in the same place. Reusable instructions can move across projects. Local details shouldn't leak, and they age faster.\n\nThis is one reason AGENTS.md fits naturally inside the AAIF project set. MCP describes how agents connect to tools. agentgateway works on routing and governing agent traffic. AGENTS.md handles repo-level behavior. You need all of those layers if agents are going to work across projects without each tool inventing its own private convention.\n\nMy workspace says: \"Skills provide your tools. When you need one, check its `SKILL.md`\n\n.\"\n\nThat's the right division of labor. `AGENTS.md`\n\nshould route the agent to deeper instructions. It shouldn't contain the full manual for every workflow.\n\nBad:\n\n```\n## Release process\n\n[900 lines of release rules, changelog policy, package registry notes, rollback steps, comms templates, and edge cases]\n```\n\nBetter:\n\n```\n## Release process\n\nFor release work, read `skills/release/SKILL.md` before making changes. Do not publish packages or create GitHub releases unless the user explicitly asks.\n```\n\nWhy does this work? The root file stays readable, and the agent loads detail only when the task needs it.\n\nThat matters more as context grows. An instruction file can hurt you if it forces every task to carry every workflow. A CSS fix doesn't need your incident response manual.\n\nThis is an important part as well that shouldn't be ignored.\n\nThe workspace `AGENTS.md`\n\nhas group chat rules. It tells the assistant to respond when directly mentioned, when it can add value, or when correcting meaningful misinformation. It also tells the assistant to stay quiet when the conversation is casual or already answered.\n\nThat's repo-relevant too. Agents need communication norms.\n\nFor a development repo, that might be:\n\n```\n## PR comments\n\n- Comment when a change affects behavior users can observe.\n- Mention test gaps plainly.\n- Don't restate the diff.\n- Don't leave speculative security claims without a concrete path or file reference.\n```\n\nAgents generate a lot of text by default. Your instructions should define what useful text looks like in your project.\n\nThe workspace instructions have a blunt rule: no \"mental notes.\" If something should persist, write it to a file.\n\nThat belongs in more repos.\n\nAgents learn project facts during a task: a flaky test command, a generated directory that shouldn't be edited, a local setup wrinkle, a service boundary that wasn't documented. If the agent only uses that knowledge once, the next run pays the same discovery cost.\n\nAdd a maintenance rule:\n\n```\n## Updating these instructions\n\nWhen you learn a durable repo rule, update `AGENTS.md` or the relevant doc in the same PR. Keep task-specific notes out of this file.\n```\n\nThen enforce the second sentence. Otherwise AGENTS.md becomes a chat transcript with headings.\n\nIf I were starting a repo-level `AGENTS.md`\n\ntoday, I'd use this shape:\n\n```\n# AGENTS.md\n\n## Start here\n\n- Read this file before making changes.\n- Read `README.md` for setup.\n- Read the nearest package-level `AGENTS.md` if one exists.\n\n## Working posture\n\n- Preserve existing patterns unless the task calls for changing them.\n- Keep edits scoped.\n- Prefer small tests close to the changed code.\n\n## Commands\n\n- Install:\n- Test:\n- Typecheck:\n- Lint:\n\n## Repo map\n\n- `apps/web`: frontend\n- `packages/api`: API client\n- `packages/db`: schema and migrations\n\n## Boundaries\n\n- Don't edit generated files.\n- Don't run destructive database commands.\n- Ask before publishing, emailing, posting, or deploying.\n\n## Workflow routing\n\n- For releases, read `docs/release.md`.\n- For security changes, read `docs/security.md`.\n- For UI changes, inspect existing components first.\n\n## Maintenance\n\n- Add durable lessons here.\n- Remove stale instructions when the code changes.\n```\n\nThat's enough for day one. It creates the framework to build upon as you continue to iterate.\n\nThe goal isn't to make the agent know everything. The goal is to make the first move reasonabe, the dangerous moves constrained, and the next file obvious.\n\nIn an open agentic ecosystem, the shared convention doesn't need to be heavy to be useful. It needs to be predictable enough that any agent can arrive in your repo and know where to begin: `AGENTS.md`\n\n.", "url": "https://wpnews.pro/news/what-a-good-agents-md-should-teach-an-agent-on-day-one", "canonical_source": "https://dev.to/bengreenberg/what-a-good-agentsmd-should-teach-an-agent-on-day-one-3nen", "published_at": "2026-08-03 15:38:29+00:00", "updated_at": "2026-08-03 15:42:53.708803+00:00", "lang": "en", "topics": ["ai-agents", "developer-tools"], "entities": ["Agentic AI Foundation", "Linux Foundation"], "alternates": {"html": "https://wpnews.pro/news/what-a-good-agents-md-should-teach-an-agent-on-day-one", "markdown": "https://wpnews.pro/news/what-a-good-agents-md-should-teach-an-agent-on-day-one.md", "text": "https://wpnews.pro/news/what-a-good-agents-md-should-teach-an-agent-on-day-one.txt", "jsonld": "https://wpnews.pro/news/what-a-good-agents-md-should-teach-an-agent-on-day-one.jsonld"}}