Ship Context, Not Docs: How AI Is Rewriting the Rules of Software Delivery
The way we deliver software to other developers is fundamentally changing. And most teams haven't noticed yet.
For decades, the developer experience playbook looked the same: write a README, create a getting started guide, maintain API documentation, build a wiki. The assumption was always that a human would read these documents, understand them, and then write code.
That assumption is now wrong — or at the very least, incomplete.
Today, the first consumer of your project's documentation is increasingly not a human. It's an AI coding agent. Claude Code, GitHub Copilot, Cursor, Windsurf — these tools are how a growing number of developers interact with codebases for the first time. And these tools don't read your beautifully formatted Confluence page. They read context files.
The Old World: Documentation for Humans
We all know what traditional documentation looks like. A README with installation steps. A "Getting Started" guide with screenshots. API reference docs generated from code comments. Architecture Decision Records buried in a wiki no one updates.
And let's be honest — even humans struggled with this model. Docs went stale the moment they were written. New joiners spent days piecing together tribal knowledge. The getting started guide assumed a setup that hadn't existed for three sprints.
The problem was never a lack of documentation tools. The problem was that documentation lived outside the development workflow. It was a second-class citizen, maintained out of guilt rather than necessity.
The New World: Context Files as Documentation
Something different is happening now. Developers are creating files that live inside the repository, written specifically to give AI tools the context they need to work effectively with the codebase. And these files are becoming the most accurate, most up-to-date documentation in the entire project.
Here's what this looks like in practice across the major AI tools:
CLAUDE.md — Claude Code's Project Memory
When you use Claude Code, it automatically reads a CLAUDE.md file from your project root at the start of every session. This file becomes the AI's persistent understanding of your project — the architecture, the conventions, the commands, the things it should never do.
A typical CLAUDE.md might include:
# Project Context
This is a Node.js microservices platform using TypeScript.
We use pnpm workspaces for monorepo management.
## Key Commands
- `pnpm test` — runs all tests
- `pnpm build` — builds all packages
- `pnpm lint` — runs ESLint + Prettier check
## Architecture
- /packages/api — Express REST API
- /packages/worker — Bull queue processors
- /packages/shared — Shared types and utilities
## Conventions
- Use 2-space indentation
- All API endpoints must have integration tests
- Never import directly from /shared/internal
- Commit messages follow conventional commits
This isn't documentation in the traditional sense. It's a briefing document. It's what you'd tell a competent new team member on their first day — except the new team member has perfect recall and will follow every instruction exactly.
The Claude Code ecosystem has taken this further with hierarchical context: a global ~/.claude/CLAUDE.md for personal preferences, project-level files for repo-specific context, and .claude/rules/ directories for path-scoped instructions that only activate when working on specific parts of the codebase. There's also SKILL.md files in .claude/skills/ — reusable workflows that Claude loads on demand for specialised tasks like generating documents, running migrations, or scaffolding components.
.github/copilot-instructions.md — GitHub Copilot's Rulebook
GitHub Copilot takes a similar approach. You create a .github/copilot-instructions.md file, and Copilot automatically includes it as context for every chat and agent request within that repository.
But GitHub has gone further with path-specific instructions. You can create multiple .instructions.md files under .github/instructions/, each scoped to specific files or directories using YAML frontmatter:
---
applyTo: "src/api/**/*.ts"
---
All API handlers must:
- Validate input using Zod schemas
- Return standardized error responses
- Include request tracing headers
- Log to structured JSON format
This means your backend code gets different AI guidance than your frontend code. Your test files get different instructions than your production code. The AI adapts its behaviour based on where it's working in your project.
But instructions are just the beginning. GitHub has built an entire composable system of context primitives inside your .github/ directory:
Skills (.github/skills/<skill-name>/SKILL.md) are self-contained folders of instructions, scripts, and resources that Copilot loads automatically when relevant to your task. Think of them as reusable playbooks — an incident triage workflow, a CI/CD troubleshooting guide, or a testing pattern specific to your project. When you ask Copilot something that matches a skill's description, it loads the full instructions and follows them, including any bundled scripts or templates.
Reusable Prompts (.github/prompts/<name>.prompt.md) are pre-written workflows you invoke with a slash command. Type /deploy-checklist in chat and Copilot executes a multi-step deployment verification process your team defined once and everyone reuses. This is the "getting started guide as a prompt" idea made real.
Custom Agents (.github/agents/<name>.agent.md) let you create specialised personas — a Security Reviewer that can only read code and run linters but never edit files, or a Planner agent that outputs an implementation plan before handing off to an Implementation agent. Each agent gets its own tool set and constraints.
Chat Modes (.github/chatmodes/<name>.chatmode.md) define predefined configurations that tailor AI behaviour for specific tasks — a DBA persona with access to database tools, or a code reviewer focused only on performance patterns.
Hooks sit underneath everything, executing custom shell commands at key points during agent execution — enforcing linting, running security scans, or logging actions regardless of which other primitive triggered the work.
The key insight from GitHub's design is that these aren't competing features — they're a composable system. A custom agent can reference instruction files. A prompt can run inside a specific agent. A skill can bundle scripts that any agent invokes. Hooks enforce hard gates at execution time. Together, they form a complete "AI developer experience" that lives entirely inside version-controlled files in your repository.
GitHub also supports AGENTS.md files — a cross-tool standard that works with Copilot, Claude Code, and other AI agents, giving you a single instruction file that multiple tools can understand.
.cursorrules and .cursor/rules/ — Cursor's Configuration Layer
Cursor uses .cursorrules files (and the newer .cursor/rules/ directory) to customise AI behaviour per project. These files tell the AI what framework you're using, what patterns to follow, and critically, what patterns to avoid.
A typical .cursorrules might look like:
You are working on a Next.js 14 app with App Router, TypeScript, and Tailwind CSS.
## Tech Stack
- Framework: Next.js 14 (App Router, Server Components by default)
- Language: TypeScript (strict mode)
- Styling: Tailwind CSS, no CSS modules
- State: Zustand for client state, TanStack Query for server state
- Testing: Vitest + React Testing Library
## Patterns to Follow
- Use Server Components unless client interactivity is needed
- Co-locate components with their tests: Button.tsx + Button.test.tsx
- All API calls go through /lib/api/ — never fetch directly in components
- Use Zod schemas for all form validation and API responses
- Error boundaries at route segment level, not per component
## Patterns to Avoid
- Never use "use client" at page level — push it to leaf components
- Never use barrel exports (index.ts re-exports) — they break tree shaking
- Never use any — use unknown + type narrowing instead
- Do not use relative imports beyond one level — use @/ path alias
The Cursor community has built an entire ecosystem around this. Sites like cursor.directory offer pre-built rule sets for every framework and language combination — drop in a React + TypeScript ruleset and Cursor immediately knows your conventions.
The newer rules system supports different activation modes: always-on rules, rules that auto-attach based on file patterns, and rules the agent can request when it determines they're relevant. It's documentation that activates contextually.
The New Documentation Stack: A Complete Comparison
To put it all together, here's how the old documentation model maps to the new context file model across every major AI tool. This is the shift in software delivery documentation happening right now:
| Purpose |
Old World |
Claude Code |
GitHub Copilot |
Cursor |
| Project context & conventions |
README.md, Wiki, Confluence |
CLAUDE.md |
.github/copilot-instructions.md |
.cursorrules |
| Path-specific rules |
Inline comments, tribal knowledge |
.claude/rules/*.md |
.github/instructions/*.instructions.md |
.cursor/rules/*.mdc |
| Reusable workflows |
Runbooks in wiki, bookmarked Slack threads |
.claude/skills/*/SKILL.md |
.github/skills/*/SKILL.md |
— |
| Getting started / task prompts |
Getting Started guide, onboarding docs |
Prompt in conversation |
.github/prompts/*.prompt.md |
— |
| Specialised personas |
"Ask Dave, he knows the auth system" |
— |
.github/agents/*.agent.md |
— |
| Interaction modes |
— |
— |
.github/chatmodes/*.chatmode.md |
— |
| Automation guardrails |
CI/CD scripts, pre-commit hooks |
Hooks |
Hooks |
— |
| Cross-tool compatibility |
— |
AGENTS.md |
AGENTS.md |
AGENTS.md |
| Personal preferences |
"My setup notes" in Notes app |
~/.claude/CLAUDE.md |
~/.copilot/copilot-instructions.md |
Global Rules in settings |
A few things stand out from this table:
The old "documentation" was scattered across a dozen tools — wikis, READMEs, Confluence, Slack bookmarks, tribal knowledge in people's heads. The new model consolidates everything into version-controlled files that live alongside the code.
GitHub Copilot has the broadest surface area with skills, prompts, agents, chat modes, and hooks forming a full composable system. Claude Code focuses on depth with hierarchical context and skills. Cursor keeps it simple with rules files and a strong community ecosystem.
The "Ask Dave" problem is being solved by files. That senior engineer who knows how the auth system works? Their knowledge now lives in a custom agent definition or a skill file that the entire team — and their AI tools — can access.
Every tool supports AGENTS.md as a cross-tool standard. This means you can write one set of core instructions and have them work across Claude Code, Copilot, and other AI agents. Invest here first.
Why This Matters for Software Delivery
This isn't just a tooling trend. It represents a fundamental shift in how software should be packaged and delivered.
Context Files Are Always Up-to-Date
Here's the key insight: developers actually maintain context files because they use them every day. When your CLAUDE.md has a wrong build command, you notice immediately because the AI fails. When your Confluence page has a wrong build command, you don't notice until a new joiner wastes half a day.
Context files create a feedback loop that traditional documentation never had. The documentation is consumed constantly, by an agent that will faithfully execute whatever it says, which means inaccuracies surface and get fixed fast.
Prompts Are the New Getting Started Guide
Think about what a "Getting Started" guide really is. It's a series of instructions: clone this, install that, run this command, check this output. It's procedural. It's sequential. It's... a prompt.
The most effective onboarding experience for a new developer using AI tools isn't a 15-page guide — it's a well-crafted prompt that says: "Set up a local development environment for this project, run the tests, and verify everything works." Combined with good context files, the AI can execute this end-to-end, asking for human input only when it genuinely needs it.
Forward-thinking teams are starting to include ready-made AI context across their repos. Here's what a fully AI-native repository structure looks like in 2026:
├── CLAUDE.md # Claude Code project context
├── AGENTS.md # Cross-tool agent instructions
├── .github/
│ ├── copilot-instructions.md # Copilot global instructions
│ ├── instructions/
│ │ └── api.instructions.md # Path-specific rules
│ ├── prompts/
│ │ ├── setup-local-env.prompt.md # Onboarding prompt
│ │ └── add-api-endpoint.prompt.md # Feature workflow prompt
│ ├── agents/
│ │ ├── security-reviewer.agent.md # Read-only security persona
│ │ └── planner.agent.md # Architecture planning agent
│ ├── chatmodes/
│ │ └── dba.chatmode.md # Database expert mode
│ └── skills/
│ └── incident-triage/
│ └── SKILL.md # Reusable triage playbook
├── .claude/
│ ├── rules/ # Path-scoped Claude rules
│ └── skills/ # Claude Code skills
├── .cursorrules # Cursor project rules
└── .cursor/rules/ # Scoped Cursor rules
Each file is a piece of the AI developer experience — version-controlled, team-shared, and consumed every single day. This is the new getting started guide. This is what onboarding looks like in 2026.
The SDK of the Future Ships with a CLAUDE.md
If you maintain a library, an SDK, or any software that other developers consume, think about this: the developers using your tool are increasingly going to interact with it through AI agents. The quality of the experience they have is going to depend not just on your API design, but on how well their AI agent understands your tool.
This means shipping your package with context files is no longer optional — it's part of the developer experience. A CLAUDE.md or copilot-instructions.md that explains your library's conventions, common pitfalls, and best practices will directly improve the code that AI agents generate when using your tool.
If you're running a platform team or internal developer platform, this shift has concrete implications:
CI/CD pipelines should validate context files. Just as you lint code and check for test coverage, you should verify that context files exist and are consistent with the actual project structure. A CLAUDE.md that references a build command that doesn't exist is a bug.
Templates and scaffolding should include context files. When your platform generates a new service from a template, that template should include pre-configured CLAUDE.md, copilot-instructions.md, and .cursorrules files appropriate for your organisation's stack and conventions.
Internal documentation strategy should evolve. The best documentation strategy isn't "write docs in Confluence" or "write context files instead." It's recognising that these serve different audiences. High-level architecture, decision rationale, and business context still belong in human-readable docs. Build commands, conventions, file structure, and coding patterns belong in context files.
Onboarding metrics will change. Instead of measuring "time to first commit," we should be measuring "time to first AI-assisted feature." The teams that have good context files will see dramatically faster onboarding for developers who use AI tools — which is rapidly becoming all of them.
The Practical First Step
If you take one thing from this post, make it this: go to your most important repository and create a CLAUDE.md file. Put in it the things you'd tell a new team member on day one:
What the project does (one paragraph)
How to build and test it (the actual commands)
The project structure (what lives where)
The conventions that matter (naming, patterns, things to avoid)
Common pitfalls (the things that always trip people up)
Then create a .github/copilot-instructions.md with the same content. And a .cursorrules file if your team uses Cursor.
You'll notice something interesting: within a week, these files will be more accurate than any documentation you've maintained in the past year. Because you'll be using them every single day, and when they're wrong, you'll feel it immediately.
The Future Is Context-Engineered
We're moving from a world where software is documented to a world where software is context-engineered. The distinction matters. Documentation is something you write after the fact for someone who might read it someday. Context engineering is something you build alongside your code, for an agent that will consume it in every session, every day.
The teams that understand this shift will ship faster, onboard developers faster, and build more consistent codebases. The teams that don't will wonder why their AI tools seem so much less effective than everyone else's.
The new documentation is a context file. The new getting started guide is a prompt. The new developer experience is AI-native.
Ship context, not just docs.
What context files is your team using? I'd love to hear what's working for you. Find me on Hashnode or drop a comment below.
