Docs for humans and docs for agents

A repository hosts documents for two kinds of readers: humans, and code-assistant agents (LLM-based IDE assistants and AI coders). This article covers the standards and conventions for both.

1. Standards for human-facing docs

README — a convention solidified in Unix software distribution around the 1980s. An all-uppercase text file at the top of a package guides users to read it first. After GitHub's launch in 2008, automatic README rendering on a repo's first page made it a de facto standard.

A typical structure:

• Project introduction and purpose
• Install and run
• Usage and examples
• How to contribute (or split into CONTRIBUTING.md)
• License

CONTRIBUTING.md — GitHub uses it as an automatic guidance link when creating Issues/PRs. Per-project PR procedures, code style, test runs.

CODE_OF_CONDUCT.md — Contributor Covenant (Coraline Ada Ehmke, 2014) is the most widely used template. A community code of conduct.

RFC process — a convention of gathering and discussing big change decisions in a document. The origin is IETF's Request for Comments (1969~). Internal RFCs at software companies borrow the same name to explicitly record "why, what, and how" of a change. Rust's RFC repository often serves as the OSS standard.

ADR — Architecture Decision Record — sourced from Michael Nygard's 2011 article "Documenting Architecture Decisions". One short document per decision (context, decision, consequences). Accumulate them in a folder like docs/adr/ to chronologically trace decision rationale.

2. Conventions for agent-facing docs

After LLM-based code assistants emerged, conventions for instruction files placed in repos grew per tool. There is no unified standard, but the following are common:

GitHub Copilot:

• Repo-level instructions — .github/copilot-instructions.md (auto-applied at repo root).
• Path-specific instructions — .github/instructions/<NAME>.instructions.md. YAML frontmatter applyTo specifies scope by glob.
• Agent-style instructions — AGENTS.md, CLAUDE.md, GEMINI.md, etc.

Cursor — .cursor/rules/*.mdc (current) or .cursorrules (legacy). Project-level instructions.

Anthropic Claude Code:

• CLAUDE.md (repo root) — read first during work.
• User-global instructions — ~/.claude/CLAUDE.md.

OpenAI — AGENTS.md has settled as the convention OpenAI's code agents reference.

Common patterns:

• Build / run / test methods
• Folder structure, SSOT locations
• Code style, prohibitions
• Domain term definitions

3. Sharing between the two kinds of docs

Both kinds of docs often need to know the same fact. The safe pattern is to designate one as SSOT and have the other reference it via link or summary.

Fact	Recommended SSOT
Build commands	README.md (human) → agent instruction file links to it
Domain glossary	docs/glossary.md
Folder structure rules	docs/architecture.md or agent instructions
Security · secrets policy	SECURITY.md

If you redo all human-facing info inside agent instructions, missed updates pile up. The commonly recommended split is to keep agent instructions limited to "how the agent should behave in this repo", while pointing to human-facing docs for facts themselves.

4. Common shapes

File split at the repo root:

README.md                  # Project intro, install, usage
CONTRIBUTING.md            # How to contribute, code style
CODE_OF_CONDUCT.md         # Community code of conduct
SECURITY.md                # Vulnerability reporting channel
LICENSE                    # License text
docs/
  adr/                     # Decision records
  architecture.md          # Folders, dependency rules
CLAUDE.md                  # Claude Code instructions
AGENTS.md                  # OpenAI agent instructions
.github/
  copilot-instructions.md  # Copilot instructions
  instructions/
    backend.instructions.md

A single ADR (Nygard format):

# 0007. Adopt PostgreSQL as RDB

## Context
- Transactional ACID required
- Team operational experience — PostgreSQL > MySQL

## Decision
- Adopt PostgreSQL 16. Operate via managed RDS.

## Consequences
- Can leverage features like JSONB and CTE
- MySQL-compatible tools cannot be used

5. Common pitfalls

When a README is too long for people to read to the end — put essentials at the top and split details into docs/.

Tools follow stale facts because the agent instruction file isn't updated — facts that are essentially code are safer extracted from the code itself (package.json commands).

An internal RFC stays in "under discussion" forever because it isn't updated after the decision — clearly mark a status label at decision time (Accepted / Rejected / Superseded by #N).

Same fact split across README, agent instructions, and ADR — pick one SSOT and link from the rest.

Closing thoughts

In an era when humans and agents handle the same repository together, the doc split will only grow more important. Same fact in one place (SSOT), other places link. Replicating every fact into agent instructions accumulates missed updates. Whatever tool — CLAUDE.md, AGENTS.md, Cursor rules, Copilot instructions — the core stays the same: write only the behavior, point to the facts.

Next

• korean-first
• no-ai-credit

GitHub Adding repository custom instructions for Copilot · Anthropic Claude Code official docs · Cursor Rules official docs · Contributor Covenant · Michael Nygard Documenting Architecture Decisions · Rust RFCs repository · Keep a Changelog · Make a README for reference.