5 Markdown Files That Tame Non-Deterministic AI in Your Engineering Org

shakti mishra — Fri, 24 Apr 2026 00:08:51 +0000

Your AI Coding Agent Has No Memory. These 5 Files Fix That.

Picture this: two developers on the same team, same repo, same AI coding assistant. One gets perfectly typed TypeScript with tests. The other gets any everywhere and zero test coverage. Same tool. Same codebase. Completely different output.

This is not a bug. It is the default state of AI-assisted engineering when you leave standardization up to individual prompting habits.

One developer's Copilot generates tests for every function. Another skips testing entirely. One team receives code that reuses the shared auth module. Another ends up with a custom, hand-rolled auth flow. One developer's output follows established naming conventions. Another produces code that looks like it came from a completely different codebase.

As AI becomes embedded in software delivery, the real problem is not capability — it is consistency. The rules, workflows, and context that shape good engineering decisions need to live somewhere permanent. Somewhere the model will actually read.

That somewhere is your repository. And the format is five markdown files.

Why Prompting Alone Doesn't Scale

Every engineer prompts differently. That is fine for a solo project. It is a slow disaster for a team.

When everyone relies on personal prompting habits, you get a system where quality varies by individual, standards drift across branches, good decisions made once never get inherited by the next PR, and AI agents context-switch between contributors with no shared memory.

The models are not the bottleneck. Your team's ability to encode engineering judgment into the system around the model is.

GitHub now supports a structured set of repository-level files that give AI coding agents a persistent, shared understanding of how your team works. These files load into context automatically, apply to specific code paths, define specialist roles, and package reusable workflows. They work across GitHub Copilot, Claude Code, Cursor, and Codex.

Here is how each one works — and why it matters.

1. `.github/copilot-instructions.md` — The Always-On Standards Layer

This is your baseline. It applies to every AI interaction in the repo, automatically, without anyone having to remember to include it.

Put broad engineering expectations here: coding conventions, testing requirements, accessibility standards, architectural boundaries, documentation rules, error-handling patterns. If your team wants the AI to always write typed APIs, follow a specific folder structure, or update tests whenever production code changes — this is where that lives.

It is one of the highest-leverage files you can create. Not because it does anything new, but because it makes implicit standards explicit and permanent.

# .github/copilot-instructions.md

## Language and framework
- Use TypeScript with strict mode enabled
- Use Express.js for all API endpoints
- Never use `any` type

## Testing
- Write unit tests for every new function using Jest
- Maintain minimum 80% code coverage

## Error handling
- Use custom error classes from `src/errors/`
- Always return structured error responses with status code and message

## Architecture
- Never import directly from `src/internal/`
- Use the repository pattern for all database access
- All new endpoints must go through the API gateway in `src/gateway/`

Think of it as onboarding documentation that never gets ignored, because the AI reads it every time.

2. `.github/instructions/*.instructions.md` — The Path-Scoped Layer

Most real codebases are not uniform. Your frontend follows different rules than your infrastructure. Your data pipelines need different guardrails than your API layer.

Path-specific instruction files let you apply the right constraints in the right place. Each file uses an applyTo pattern to activate only for matching directories or file types. This is where standardization gets intelligent instead of blunt.

---
applyTo: "src/frontend/**"
---
# Frontend instructions
- Use React functional components with hooks
- Use Tailwind CSS for styling, no inline styles
- All components must be accessible (WCAG 2.1 AA)
- Use React Testing Library for component tests

---
applyTo: "infrastructure/**"
---
# Infrastructure instructions
- Use Bicep for all Azure resource definitions
- Never hardcode secrets, always reference Key Vault
- Tag every resource with `environment` and `team`

You stop treating the repo like a monolith and start giving the AI the right lens for each context. The frontend agent should not be applying infrastructure conventions. Now it will not.

3. `AGENTS.md` — The Repo's Operating Manual

This is the file that tells an autonomous agent how work actually gets done here.

AGENTS.md is an open format for guiding coding agents, originally created by the OpenAI ecosystem. GitHub's Copilot coding agent added support for it in 2025, and the industry has converged around it: GitHub also supports CLAUDE.md and GEMINI.md as equivalent alternatives, depending on your toolchain.

Think of it as operational memory for the repo. What commands should the agent run? How should it test? What should it never touch? How should it title pull requests? What counts as "done"?

Without this file, every autonomous agent starts from scratch. With it, engineering standards become portable across tools and contributors.

# AGENTS.md

## Build and test
- Run `npm run build` before committing
- Run `npm test` and ensure all tests pass
- Run `npm run lint` and fix all warnings

## Pull requests
- Title format: `[AREA] Short description`
- Always include a summary of what changed and why
- Never push directly to `main`

## Off limits
- Do not modify files in `src/generated/`
- Do not update `package-lock.json` manually
- Do not change CI/CD workflows without approval

The distinction from copilot-instructions.md is important. That file sets coding standards. This one sets operating procedure. One shapes what the AI produces. The other shapes how it behaves as an agent.

4. `.github/agents/*.md` — Custom Agent Profiles (The Specialist Layer)

Not every task should go to a general-purpose coding assistant. Sometimes you need a security reviewer who will not touch production code. Sometimes you need an implementation planner. Sometimes you need a refactoring specialist with write access to exactly two directories.

Custom agent files let you define specialist personas with their own instructions, tools, and restrictions. They live in .github/agents/ and can specify which tools the agent is allowed to use — including MCP servers if your setup supports them.

# .github/agents/security-reviewer.md
---
description: "Reviews code for security vulnerabilities"
tools:
  - code_search
  - read_file
---

You are a security reviewer. Your job is to find vulnerabilities.

## Rules
- Flag any use of `eval()`, `innerHTML`, or unsanitized user input
- Check for SQL injection in all database queries
- Verify that all API endpoints require authentication
- You may read code but never modify it
- Output a structured report with severity levels

This is architecturally different from general instructions. General instructions tell every agent how your team works. Custom agents create intentional specialists for jobs that repeat. You define the role once, and any developer on the team can invoke it without reinventing the persona each time.

The repo stops having one AI assistant with inconsistent behavior. It starts having a team of specialists with defined roles.

5. `SKILL.md` — The Reusable Capability Layer

This is where things get genuinely powerful.

A skill is a folder of instructions, scripts, and resources that an agent loads on demand for a specific task. It lives under .github/skills/ and must include a SKILL.md file. GitHub has made the spec an open standard, and skills work across Copilot's coding agent, the CLI, and VS Code agent mode.

The difference between a skill and a custom instruction is that a skill can package a repeatable workflow — not just guidance, but executable steps with associated scripts.

.github/skills/
  debug-ci/
    SKILL.md
    scripts/
      analyze-logs.sh

# SKILL.md
---
name: "debug-ci"
description: "Debug failing GitHub Actions workflows"
---

## Steps
1. Read the failing workflow YAML from `.github/workflows/`
2. Run `scripts/analyze-logs.sh` to extract the error
3. Check if the failure is a flaky test, dependency issue, or config error
4. Suggest a fix with the exact file and line to change
5. If the fix involves a dependency update, run `npm audit` first

You can build skills for anything that happens more than twice: Playwright UI testing, infrastructure code review, proposal drafting, schema validation, changelog generation. The team stops starting from zero on recurring tasks. Good engineering behavior becomes a reusable asset.

How the Layers Stack Together

Here is how the full system looks when all five files are in play:

┌─────────────────────────────────────────────────────┐
│                    Your Repository                   │
│                                                      │
│  ┌──────────────────────────────────────────────┐   │
│  │  copilot-instructions.md                     │   │
│  │  Always-on: coding standards, arch rules     │   │
│  └──────────────────────────────────────────────┘   │
│                                                      │
│  ┌──────────────────────────────────────────────┐   │
│  │  .github/instructions/*.instructions.md      │   │
│  │  Path-scoped: frontend rules, infra rules    │   │
│  └──────────────────────────────────────────────┘   │
│                                                      │
│  ┌──────────────────────────────────────────────┐   │
│  │  AGENTS.md                                   │   │
│  │  Operating manual: build, test, PR rules     │   │
│  └──────────────────────────────────────────────┘   │
│                                                      │
│  ┌──────────────────────────────────────────────┐   │
│  │  .github/agents/*.md                         │   │
│  │  Specialist roles: security, planner, etc.   │   │
│  └──────────────────────────────────────────────┘   │
│                                                      │
│  ┌──────────────────────────────────────────────┐   │
│  │  .github/skills/*/SKILL.md                   │   │
│  │  Reusable workflows: debug-ci, test-ui, etc. │   │
│  └──────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────┘
                          │
                          ▼
         ┌────────────────────────────┐
         │   AI Coding Agent          │
         │   (Copilot / Claude Code / │
         │    Cursor / Codex)         │
         └────────────────────────────┘

Each layer handles a different surface area. Together, they close the gap between what the model can do and what your team needs it to do consistently.

The Shift Most Teams Miss

Most teams reach for more model power when they hit inconsistency problems. A better model will not fix a context problem.

The real insight is this: your AI coding tools are only as consistent as the context they receive. When that context is scattered across Slack threads, tribal knowledge, and individual senior engineers, the AI inherits that chaos. When it lives in structured, version-controlled files, the AI inherits your engineering judgment.

These five files are not markdown clutter. They are the beginning of a standardized interface between your engineering system and the AI agents working inside it.

The best teams will not win because they have access to the smartest model. They will win because they know how to encode their engineering judgment into the system around the model.

And increasingly, that system looks like this:

copilot-instructions.md for the default rules
AGENTS.md for the repo's operating manual
Path-specific files for context-aware standards
Custom agents for specialist roles
SKILL.md for reusable workflows The future of software engineering will not just be written in code. More of it will be written in context.

Key Takeaways

AI coding tools are only as consistent as the context they receive. Without structured repo files, every developer's output diverges based on personal prompting style.
The 5-file system creates layered, version-controlled context — always-on standards, path-scoped rules, operating procedures, specialist personas, and reusable workflows.
AGENTS.md is cross-tool portable. GitHub Copilot, Claude Code, and Gemini all support their own flavor; the concept is converging into an industry standard.
Skills package repeatable workflows, not just instructions. If a task happens more than twice, it should be a skill.
Most teams need more structure before they need more model power. Better context produces more consistent output than a smarter model with no guardrails.

What Are You Doing About This?

Most teams I talk to are one or two steps into this system — they have a rough copilot-instructions.md or a stale AGENTS.md that nobody updates. Very few have all five layers running together.

Which of these files does your team already have in place? And which one would make the biggest difference if you added it tomorrow?

Drop a comment — I'm curious where teams are actually getting value and where they're still fighting entropy.

Credit: The technical insights in this post draw from Diary of an AI Architect by Anurag Karuparti — one of the clearest voices on production agentic AI architecture.

DEV Community: shakti mishra