Make your repository AI-ready by giving the coding agent a short, accurate, version-controlled briefing in the format its specific tool supports. Explain what the project does, where important code lives, which conventions matter, and the verified commands for building and testing. Then confirm that the agent discovers the guidance and handles a representative task better.
What does it mean for a repository to be AI-ready?
An AI-ready repository gives a coding assistant reliable project context it may not infer from source code alone: the system’s purpose, its architecture, team conventions, and how to validate a change. The goal is not to add a large prompt or a generic list of programming rules. It is to reduce repeated corrections and help the agent choose appropriate files, follow local patterns, and run the right checks.
As Microsoft puts it in its Configure AI for your codebase guide: “AI agents can produce better results when they understand how your codebase is structured, which commands to run, and which conventions to follow.” That is useful context, not a promise of consistent compliance or a substitute for review.
Choose the instruction file for the agent you actually use
There is no single instruction filename that every coding assistant and feature reads. Check the current guidance for the exact product, editor, and workflow your team uses before standardizing. Microsoft’s VS Code format guide lists these options:
#1 Best Overall
- Read Before You Buy — No Video Output: These adapters support charging and USB 2.0 data transfer, but cannot transmit video signals. Except for standard USB webcams (which use USB data only), they are not compatible with HDMI/DisplayPort cables, video-capable USB-C hubs, or docking stations with video output.
- Convert USB-A Ports to USB-C: Designed to connect USB-C earphones, cables, flash drives, card readers, and other USB-C accessories to standard USB-A ports. Plug-and-play with no drivers or software required.
- Aluminum Alloy Housing: Built with a sturdy aluminum alloy shell that aids in heat dissipation and protects against daily wear and scratches. Designed to maintain a stable and secure connection.
- Compact & Travel-Friendly: The ultra-compact design allows the adapter to stay plugged into your device without blocking adjacent ports or adding bulk, reducing wear and tear on your original USB ports.
- 12-Month Warranty: Backed by a 12-month manufacturer warranty for peace of mind. Designed to meet strict quality control standards for reliable everyday performance.
| Tool or context | Documented project-wide format | Scoped or complementary options | Important qualification |
|---|---|---|---|
| GitHub Copilot on GitHub | .github/copilot-instructions.md |
.github/instructions/**/*.instructions.md; AGENTS.md. GitHub also mentions CLAUDE.md or GEMINI.md as alternatives in its guidance. |
Support differs by Copilot feature. The nearest AGENTS.md takes precedence, and matching path-specific guidance can be used alongside repository-wide guidance. See GitHub’s repository-instructions documentation. |
| Copilot in VS Code | .github/copilot-instructions.md or AGENTS.md |
.github/instructions/**/*.instructions.md |
Check behavior for the specific host and session; do not assume every Copilot feature reads every format. See Microsoft’s VS Code guide. |
| Claude in VS Code or Claude Code | CLAUDE.md |
.claude/rules in VS Code; root and subdirectory CLAUDE.md files for Claude Code |
Anthropic says Claude Code reads CLAUDE.md at session start for the current directory; subdirectory guidance is loaded on demand when files there are read. See Anthropic’s context guide. |
| OpenAI Codex in VS Code | AGENTS.md |
AGENTS.md files in subfolders |
This is the format listed by the current VS Code guide. Confirm discovery behavior in the active Codex harness before relying on tool-specific rules. See Microsoft’s VS Code guide. |
For Copilot, GitHub’s statement is specific: “Repository custom instructions let you provide Copilot with repository-specific guidance and preferences on GitHub.” The GitHub Docs article also describes the formats and their feature-specific behavior. A file’s presence in Git is not proof that a particular assistant feature reads it.
Audit the repository before writing guidance
- Start with a real friction point. Record which files an agent changes, which project patterns it misses, which commands it skips or gets wrong, and what corrections maintainers repeatedly give. If the agent already meets the team’s success criterion, extra instructions may not help.
- Read the existing sources of truth. Check the README, contribution guide, package and build files, CI workflows, and any existing instruction files. Preserve useful guidance and resolve contradictions rather than duplicating accurate documentation. Review the diff when editing an instruction file instead of replacing it wholesale.
- Verify details from project configuration. Derive build, test, lint, and setup commands from package scripts, build configuration, CI, or maintainer-confirmed instructions. Do not add a plausible command as though it were tested. Mark uncertain details for a human to confirm.
Microsoft recommends this observed-problem approach in Configure AI for your codebase, including reviewing existing guidance before making changes.
Rank #2
- 5-in-1 USB-C Hub: Experience comprehensive connectivity featuring a Power Delivery input, two USB-A 2.0 ports, a USB-A 3.0 port, and an HDMI port. (Note: The USB-C power delivery input port is only for connecting an external wall charger to power your laptop and cannot power peripheral devices.)
- 90W Pass-Through Charging: Achieve optimal charging with 90W pass-through power to your laptop, supported by a total input of 100W, with the hub reserving 10W for operational efficiency. (Note: Wall charger not included.)
- Quick Data Transfers: Accelerate your productivity with rapid data transfers using a high-speed 5Gbps USB 3.0 port and two 480Mbps USB 2.0 ports.
- 4K HDMI Display: Enhance your visual experience with a hub capable of delivering 4K resolution at 30Hz in both mirror and extend modes. Please note that this hub is compatible with MacBook (macOS 12 and newer), Windows 10 and 11, ChromeOS, and laptops equipped with DP Alt Mode and Power Delivery. Note: This device is not compatible with Linux.
- What You Get: Anker USB-C Hub (5-in-1, 4K HDMI), welcome guide, 18-month warranty, and our friendly customer service.
What to put in a root instruction file
Keep the root file a compact orientation to the repository. Include the facts that help the agent act correctly across ordinary tasks, not a tutorial or an exhaustive copy of the README.
- Purpose and users: One or two sentences on what the repository builds and who uses it.
- Stack: The main languages, frameworks, runtime, package manager, and build system, when known.
- Architecture map: Important directories and anchor files, with a short description of each. Explain relationships or constraints that are not obvious from names or code.
- Verified commands: Exact setup, build, lint, test, and validation commands that are accepted for this repository. Say when a command applies only to a package or subsystem.
- Local conventions: Project-specific naming, formatting, architectural, and error-handling rules that an agent cannot reliably infer.
- Change expectations: Where tests belong, what validation a change should include, and any requirement to report checks run, failed, or skipped.
- Non-obvious constraints: For example, generated files that should not be edited directly or compatibility commitments maintainers expect changes to preserve.
GitHub’s repository-instructions guide recommends project purpose, repository information, and structurally important files; its example says suggested instructions should be no longer than two pages and not task-specific. Treat that as a ceiling for the example, not a target length: include only what is useful in your codebase.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Rank #3
- Sleek 7-in-1 USB-C Hub: Features an HDMI port, two USB-A 3.0 ports, and a USB-C data port, each providing 5Gbps transfer speeds. It also includes a USB-C PD input port for charging up to 100W and dual SD and TF card slots, all in a compact design.
- Flawless 4K@60Hz Video with HDMI: Delivers exceptional clarity and smoothness with its 4K@60Hz HDMI port, making it ideal for high-definition presentations and entertainment. (Note: Only the HDMI port supports video projection; the USB-C port is for data transfer only.)
- Double Up on Efficiency: The two USB-A 3.0 ports and a USB-C port support a fast 5Gbps data rate, significantly boosting your transfer speeds and improving productivity.
- Fast and Reliable 85W Charging: Offers high-capacity, speedy charging for laptops up to 85W, so you spend less time tethered to an outlet and more time being productive.
- What You Get: Anker USB-C Hub (7-in-1), welcome guide, 18-month warranty, and our friendly customer service.
Use scoped instructions for rules that really differ
Keep broadly applicable facts in the root briefing. Add path-specific guidance when a subsystem has distinct language, framework, generation workflow, or review constraints. For GitHub Copilot, path-specific .instructions.md files can complement repository-wide instructions; GitHub says matching path-specific and repository-wide guidance may both apply. For the documented Copilot behavior, the nearest AGENTS.md takes precedence.
Scoped files can reduce irrelevant context, but they also create another place to maintain. Keep overlapping rules consistent, and avoid separate instruction sets that contradict one another. GitHub discusses scope and conflicting instructions in About customizing GitHub Copilot responses. For Claude Code, Anthropic describes root and subdirectory CLAUDE.md context in its context guide.
Rank #4
- Dual Converters, Infinite Potential：Includes 2× USB C male to USB A female adapters and 2× USB A male to USB C female adapters. Perfect for a wide range of uses—tablets with Bluetooth keyboards, expand USB ports on macbook, and more. Two different converters for all your daily needs
- Next-Level 10Gbps & 3A Charging: No more slow 480Mbps, this usb to usb c adapter has a transfer speed of up to 10Gbps, allowing you to do more transferring in less time. This usb adapter fits both USB A and USB C charger, supporting up to 3A fast charging
- Upgraded Exquisite Craftsmanship: With an aluminum alloy housing and metal connector, the usbc to usb adapter is extremely durable and sturdy. Rigorously tested to withstand more than 10,000 times of plugging and unplugging, ensuring long-lasting performance
- Broad Compatible: The usb c to usb adapter widely supports all USB C/ USB A devices like laptops, tablets, cellphones, car chargers, and phone chargers. Such as compatible with MacBook Pro/Air 2023/2022, Thunderbolt 4/3 Devices,Apple MagSafe Watch 9/8/7/SE/Ultra, iPad Pro 2022/2021, Samsung Galaxy S23/S20/S10, and iPhone 17/16/15 Pro. Plug and play
- Please Note: To reach 10Gbps speed, keep the cable under 3.3 ft. For USB A Male to USB C adapters, try flipping the USB C connector. USB C Male to USB A adapters support bidirectional 10Gbps transfer within 3.3 ft
Validate that the agent finds and uses the guidance
- Pick a representative task that exposed the original problem, such as changing a feature in a specific subsystem or adding a test using the repository’s established pattern.
- Use the intended harness. Open the repository in the exact editor, coding assistant, and feature the team plans to use. Confirm the relevant instruction file is discovered; do not infer discovery merely from the file being committed.
- Make the smallest useful instruction change. Add only the project fact or rule needed to address the observed mistake.
- Repeat the task and compare outcomes. Check whether the agent chose appropriate files, followed conventions, ran the right commands, and reported checks or failures accurately. Compare with the earlier attempt where practical.
- Review the documentation change. Ensure it is accurate, non-duplicative, and consistent with the rest of the repository. Keep ordinary code review and validation in place.
Microsoft recommends repeating an observed task to check whether a customization helps. GitHub cautions that Copilot may not follow custom instructions in exactly the same way every time; instructions improve context, but they do not make behavior deterministic. See GitHub’s guidance on customizing Copilot responses.
Maintain the briefing as the repository changes
Instruction files are project documentation. Revisit them when architecture, tooling, build commands, or supported agent features change. Remove stale rules, update commands only after verifying them, and review instruction edits like other documentation changes. GitHub notes that Copilot code review uses relevant custom instructions from the pull request’s head branch, which can help a team assess proposed guidance in the same change: Using GitHub Copilot code review.
Recommended Free Tools
Quick Recap
Best Value
- 5-in-1 Connectivity: Equipped with a 4K HDMI port, a 5 Gbps USB-C data port, two 5 Gbps USB-A ports, and a USB C 100W PD-IN port. Note: The USB C 100W PD-IN port supports only charging and does not support data transfer devices such as headphones or speakers.
- Powerful Pass-Through Charging: Supports up to 85W pass-through charging so you can power up your laptop while you use the hub. Note: Pass-through charging requires a charger (not included). Note: To achieve full power for iPad, we recommend using a 45W wall charger.
- Transfer Files in Seconds: Move files to and from your laptop at speeds of up to 5 Gbps via the USB-C and USB-A data ports. Note: The USB C 5Gbps Data port does not support video output.
- HD Display: Connect to the HDMI port to stream or mirror content to an external monitor in resolutions of up to 4K@30Hz. Note: The USB-C ports do not support video output.
- What You Get: Anker 332 USB-C Hub (5-in-1), welcome guide, our worry-free 18-month warranty, and friendly customer service.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
