Curated Shared Instructions for Software Teams Adopt

developer-aicoding-agentsgovernanceteam-practicespromptsagents-mdcopilotrules

Overview

Curated shared instructions turn ad hoc prompts into maintained team assets for AI-assisted delivery. Teams use files such as AGENTS.md, .github/copilot-instructions.md, .cursor/rules/, and *.instructions.md to encode architecture conventions, coding standards, test expectations, security boundaries, and workflow norms for coding agents.

AGENTS.md is positioned as a README-like file for agents: a predictable place for build steps, tests, conventions, security considerations, and other context that may be too detailed or agent-specific for a human-facing README (AGENTS.md). GitHub Copilot and VS Code now also support repository-wide, path-specific, and agent-oriented instruction files, including AGENTS.md for multi-agent workspaces (VS Code custom instructions, GitHub Copilot custom instructions).

The reason to classify curated shared instructions as Adopt is that multiple people and agents now contribute to the same repositories. A maintained instruction layer is one of the lowest-cost ways to align coding agents with a team's actual build, test, review, and safety practices. The value comes from concise, specific, reviewed guidance connected to deterministic checks, not from long prompt files.

Adoption Signals

  • AGENTS.md is described as a simple, open format for guiding coding agents, with suggested sections such as project overview, build and test commands, code style, testing instructions, security considerations, commit messages, PR guidelines, and deployment steps (AGENTS.md).
  • The AGENTS.md site says nested AGENTS.md files can be used in monorepos and that the closest AGENTS.md to the edited file wins, while explicit user chat prompts override everything (AGENTS.md).
  • AGENTS.md lists support across a broad ecosystem including Codex, Jules, Factory, Aider, Goose, OpenCode, Zed, Warp, VS Code, Devin, Cursor, RooCode, Gemini CLI, GitHub Copilot, Ona, Windsurf, and others (AGENTS.md).
  • Codex reads AGENTS.md files before doing work, supports global, repository, and nested instruction files, and concatenates files from root down so closer files override broader guidance (Codex AGENTS.md).
  • Codex supports fallback instruction filenames, a project_doc_max_bytes limit, and verification commands that ask Codex to summarize active instruction sources (Codex AGENTS.md).
  • VS Code supports .github/copilot-instructions.md, AGENTS.md, CLAUDE.md, and *.instructions.md, including path-based application through glob patterns and nested AGENTS.md discovery behind settings (VS Code custom instructions).
  • GitHub Copilot supports repository-wide custom instructions, path-specific NAME.instructions.md files with applyTo frontmatter, and agent instructions through AGENTS.md files where the nearest file in the directory tree takes precedence (GitHub Copilot custom instructions).
  • GitHub’s analysis of more than 2,500 repositories found that effective agents.md files include exact commands, clear boundaries, stack details, code examples, and well-defined sections, while vague files fail (GitHub Blog).
  • Cursor recommends checking rules into git, keeping rules focused on essential commands and patterns, referencing canonical examples rather than copying long guides, and updating rules when the agent repeats mistakes (Cursor agent best practices).

Risks

  • Instruction bloat reduces signal. Cursor explicitly warns against copying entire style guides, documenting every possible command, or adding rarely used edge cases to always-on rules; linters and tests should carry deterministic enforcement instead (Cursor agent best practices).
  • Vague instructions fail. GitHub’s repository analysis says generic instructions such as “You are a helpful coding assistant” are ineffective compared with specific personas, exact commands, boundaries, and examples (GitHub Blog).
  • Conflicting instructions can degrade output. GitHub advises avoiding conflicting instruction sets, while AGENTS.md and Codex define precedence rules that teams must understand for nested files and overrides (GitHub Copilot custom instructions, Codex AGENTS.md).
  • Instructions can drift from reality. Build commands, test targets, API names, architecture decisions, and security rules change; stale instructions may cause agents to waste time or make wrong changes with confidence.
  • Client behavior differs. Codex has byte limits and fallback filename settings, VS Code applies path-specific files through glob or semantic matching, and GitHub Copilot uses base-branch instructions for PR review, so teams should test how each agent loads instructions (Codex AGENTS.md, VS Code custom instructions, GitHub Copilot custom instructions).
  • Instructions are not controls. “Never commit secrets” is helpful guidance, but it does not replace secret scanning, permission boundaries, sandboxing, code review, or branch protection.

Pros & Cons

Advantages

  • Turns repeated prompting into reviewed, version-controlled team assets that encode build commands, test expectations, architecture rules, coding style, git workflow, and safety boundaries.
  • Improves consistency across coding agents by giving them a predictable place to find repository-specific guidance before editing, testing, reviewing, or opening pull requests.
  • Scales across monorepos and mixed-agent teams through AGENTS.md, Copilot instructions, Cursor rules, path-specific instruction files, and nested overrides.

Disadvantages

  • Shared instructions can become stale, contradictory, or bloated if they are not owned, reviewed, tested, and pruned like other repository assets.
  • Instructions are guidance, not enforcement; teams still need linters, tests, type checks, security scans, branch protection, and human review.
  • Different agent clients apply precedence, file discovery, byte limits, and path-specific rules differently, so portability must be verified.

Recommendation

Adopt curated shared instructions for repositories where multiple developers or agents contribute code. Start with one concise repository-level file covering commands, testing, project structure, code style, git workflow, and boundaries. Put the most-used executable commands early, include exact flags, and prefer examples of correct code or PR output over long prose.

Maintain instructions like code. Check them into git, assign owners, review changes, remove stale guidance, and update the file when agents repeatedly make the same mistake. Use nested AGENTS.md or path-specific instructions for monorepos and framework-specific rules, but keep the nearest-file precedence model understandable.

Connect instructions to deterministic checks. Every important rule should either point to a command, linter, test, security scanner, example file, or review checklist. Move from “agent prompt” thinking to “team operating manual” thinking: the instruction file should help agents discover the right checks, not pretend to enforce them by itself.

Sources