Split View: AI 시대 개발자 영어: AGENTS.md, 시스템 프롬프트, RFC — 에이전트가 읽는 영어 쓰기의 기술

Developer English in the AI Era: AGENTS.md, System Prompts, RFCs — Writing the English Agents Read

"The most important English you write in 2026 is not read by a human. It is read by an agent."

Prologue — The audience changed

Five years ago, the reasons a developer needed strong English were obvious. To explain a tricky change in code review. To work with engineers in other timezones over an issue tracker. To give a conference talk. To answer behavioral questions in interviews. The audience was always a human.

In 2026, the most important audience for your English has shifted. The English you write the most each week is probably not a Slack message to a colleague — it is English that an agent will read. The build commands in AGENTS.md. The system prompt for your Claude Code session. The description on a Devin ticket. The PR context you hand to Codex. The RFC where you spell out non-functional requirements — and the RFC, in 2026, is the document a human writes first and an agent then breaks into executable work.

This post takes a different angle from earlier English posts on this blog. Code review English, standup English, salary-negotiation English, FDE-interview English — those were all about speaking to humans. This one is about writing English for agents — and writing English that humans and agents both read. Those two audiences are not the same, and the differences are subtle but decisive.

The thesis

The single highest-leverage form of English a developer writes in 2026, measured per minute of effort, is English that agents read.

Three reasons.

First, reuse. A Slack message is read by one person, once. AGENTS.md is read by every teammate's every agent session, every time. A one-line quality difference compounds thousands of times.

Second, literalness. Humans patch over vague writing using context. Agents do not patch — or they patch in the wrong direction. Weak English maps directly to weak behavior.

Third, leverage. One well-written line in a system prompt replaces a hundred review comments. One well-written RFC produces thirty well-shaped tasks.

What this post covers:

1. The audience changed — humans vs agents as readers

Writing good English means understanding your audience. Human readers and agent readers are clearly different audiences.

1.1 Humans patch the gaps; agents do not

You write a sentence to a colleague:

We probably want to use the new auth flow for this, unless there's a reason
to stay on the old one. Let me know what you think.

Your colleague reads five things at once. (1) A proposal to use the new flow. (2) Soft conviction (probably). (3) Openness to disagreement (unless). (4) Partial delegation of the decision (let me know). (5) A friendly tone (we). They reach all five because they know company politics, your role, your previous conversations, and the conventions of hedged English.

Feed the same sentence to an agent. The agent often picks one of two readings — either "Use the new auth flow" or "Defer, ask the user, because of probably and unless." Neither matches the human reading of "Let us decide this together."

1.2 Agents read tokens as weights

An agent does not read sentences in semantic chunks. It reads them as a weighted sum of tokens. The small words humans treat as ornament — should, must, may, prefer, always, never, consider — push the agent's behavior in measurable ways.

The takeaway — consider and perhaps feel like polite suggestions to a human reader, but to an agent they are mostly noise. For agents, Use X or Do not use X is almost always better.

1.3 Humans read once; agents read every time

AGENTS.md is reloaded every session, every task, every call. That is unlike a README, which a colleague reads once and stores in their head. A line of AGENTS.md is not a one-time cost — it is a recurring cost. One noisy line, multiplied by a thousand sessions, becomes a thousand weights.

This is why one of Anthropic's official recommendations is: for every line in CLAUDE.md, ask, "would Claude have made a mistake without this?" If the answer is no, the line is noise.

2. Agents are literal — the hedging trap

Native English speakers naturally hedge. kind of, sort of, I think, perhaps, it might be that, would probably want to. To a human, this is politeness. To an agent, it lowers signal-to-noise ratio.

2.1 Weak English vs strong English — before and after

Before — a system prompt riddled with hedges:

You should probably try to use TypeScript for new files, although JavaScript
might be acceptable in some cases. It would be nice if you could add tests,
but if you don't have time, that's okay too. Please try to follow the
existing code style as much as possible.

How the agent behaves:

• Asks the user every time whether to use TypeScript or JavaScript
• Skips tests, because "if you don't have time" is effectively a get-out clause
• Follows code style "as much as possible" — undefined threshold

After — same intent, strong English:

Write all new files in TypeScript. JavaScript is only allowed when modifying
an existing .js file in place — do not convert .js to .ts as part of an
unrelated change.

Write tests for any new function exported from a module. Tests live next to
the source as <name>.test.ts.

Follow the rules in eslint.config.js. If a rule conflicts with your output,
fix your output — never disable the rule.

How the agent behaves now:

• Writes new files in TypeScript (exceptions are explicit)
• Writes tests for every exported function
• Follows lint rules — conflict behavior is defined

Three changes did the work:

1. Remove hedges: drop probably, might, would be nice
2. Make exceptions explicit: spell out the conditions where a rule does not apply
3. Define conflict behavior: "if X conflicts with Y, do Z"

2.2 The negation trap — agents often miss negations

Long negative sentences are hard for agents.

Before:

Do not delete files unless you are sure they are not used by any other
module that you have not yet read.

Double negation plus stacked conditions, and the agent often collapses this into "delete files."

After:

Never delete a file in this session. If you believe a file is unused, list
it in your final summary under "Files I would delete" — let the user delete it.

The negation is now a single positive action plus an alternative. Agents follow negations far more reliably when there is an explicit alternative right next to them.

2.3 The "if unsure, ask" trap

If unsure, ask the user works when used carefully, but written naively it turns the agent into a question machine, because "unsure" has no threshold.

Before:

If you are unsure about anything, ask the user before proceeding.

After:

Proceed without asking when: (a) the change is a typo or comment-only fix,
(b) the test suite passes locally, (c) you can produce a unit test that
demonstrates correctness.

Ask the user when: (a) the change touches authentication or billing code,
(b) you cannot find a relevant test, (c) the change requires a new
dependency.

By replacing "unsure" with a whitelist and a blacklist, the agent becomes both more autonomous and safer.

3. AGENTS.md / CLAUDE.md — writing context files

AGENTS.md is the most important new document format of 2026. It started as a convention at OpenAI Codex, was adopted across the agent ecosystem, and is now stewarded as an open standard by the Agentic AI Foundation under the Linux Foundation. More than 60,000 open-source projects have adopted it. CLAUDE.md is the equivalent for Claude Code. Both are plain Markdown, but the gap between a good one and a bad one is large.

3.1 The four sections of a good AGENTS.md

A good AGENTS.md usually has four sections.

# AGENTS.md

## What this repo is
(So the agent does not get lost in unfamiliar code — 2 to 4 lines)

## How to build, test, run
(Terminal commands — the exact command, the exact directory)

## Conventions
(Code style, naming, file layout — things you cannot infer from the code)

## Boundaries
(What the agent must never touch)

The AGENTS.md in the OpenAI Codex repository itself follows this shape, and is striking for how short and powerful it is — a human reads it in thirty seconds, and the agent quotes from it accurately every time.

3.2 A weak AGENTS.md vs a strong AGENTS.md

Before — a common weak AGENTS.md:

# Our Project

This is a Node.js project. We try to follow best practices and write clean code.

## Getting started

You can install dependencies with npm. To run the tests, use the test command.
We use TypeScript and prefer functional patterns when it makes sense.

Please be careful when making changes and try to add tests when appropriate.
If you need to deploy, talk to the platform team.

Why this is weak:

• "best practices", "clean code" — empty signifiers
• "you can install with npm" — no exact command
• "when it makes sense" — no threshold
• "when appropriate" — no threshold

After — a strong AGENTS.md:

# AGENTS.md

## What this repo is
A Next.js 15 app for the customer billing portal. The backend is a separate
service at `api.example.com` — this repo contains only the frontend.

## Setup, build, test
- Install: `pnpm install` (do not use npm or yarn — the lockfile is pnpm)
- Dev server: `pnpm dev` (port 3000)
- Tests: `pnpm test --filter <package>` for a single package, never `pnpm test` for the whole monorepo (it takes 20 plus minutes)
- Typecheck: `pnpm typecheck` — must pass before any commit

## Conventions
- Components: PascalCase files in `src/components/`. One component per file.
- Hooks: `useFoo.ts` in `src/hooks/`. Always return an object, never an array.
- API calls: use `src/lib/api/client.ts` — never call `fetch` directly.
- Styling: Tailwind only. Do not add new CSS files.

## Boundaries
- Never modify `src/generated/` — it is regenerated from OpenAPI in CI.
- Never edit `pnpm-lock.yaml` by hand — use `pnpm install`.
- Never add a dependency without asking — the bundle is already 280 KB and we are tracking it.
- Do not touch `src/billing/legacy/` — it is being deprecated; new features go in `src/billing/v2/`.

The pattern is simple — every line gives (a) the exact command or path, (b) a short why. The "why" matters because it lets the agent generalize to edge cases the rule did not cover.

3.3 Patterns specific to CLAUDE.md

CLAUDE.md is automatically loaded into every Claude Code session. Two patterns follow from that.

Pattern 1 — permanently block a recurring mistake. When the agent makes the same mistake twice, add the lesson to CLAUDE.md.

## MDX blog rules

Files in `data/blog/` are MDX, pre-rendered at build time. Patterns that
break the build:

- A bare `{identifier}` in prose becomes a JSX expression, which throws a
  ReferenceError. Wrap in backticks or rephrase.
- A `<` followed by a digit makes MDX try to parse a JSX tag. Add a space:
  `< 100`, not `<100`.
- A code fence that opens with stray content after the language identifier
  breaks parsing.

When fixing one variant (.mdx), check all three (.mdx / .en.mdx / .ja.mdx).

Pattern 2 — surface the painful operations. Agents do not know what is slow. Tell them.

## Slow operations — avoid in agent sessions
- `pnpm install` from a cold cache: 4 minutes
- `pnpm test` for the whole monorepo: 22 minutes
- `next build`: 6 minutes
- E2E tests: 18 minutes — never run them unless explicitly asked

Prefer: `pnpm test --filter <pkg>`, `pnpm typecheck`, `pnpm lint`.

This one section alone prevents the agent from casually running tests and burning twenty-two minutes of its session.

4. System prompts — English for production agents

If AGENTS.md is "context about this codebase," a system prompt is "definition of the agent." For a production agent, the two must be cleanly separated.

4.1 The five sections of a system prompt (Anthropic's pattern)

Following Anthropic's prompt engineering guide:

1. Role and persona       — who you are
2. Context                — the environment you operate in
3. Capabilities and tools — what you can do
4. Rules and constraints  — what you absolutely cannot do
5. Output format          — how to return results

Example — skeleton for a customer support agent:

ROLE
You are the support assistant for Example Corp. You handle questions about
billing, account access, and subscription changes. You do not handle
refunds — those are escalated to a human agent.

CONTEXT
You have access to the user's account through the get_account tool. You do
not have access to payment methods, internal Slack, or engineering tickets.
The current date is in the user message.

CAPABILITIES
- Look up account state with get_account
- Trigger a password reset with send_password_reset
- Open a refund ticket with create_refund_ticket (this hands off to a human)

RULES
- Never reveal another user's data.
- Never tell the user about internal tools or model names.
- If the user asks for a refund, do not promise it — create a ticket and tell
  them a human will follow up within one business day.
- If you are unsure whether an action is allowed, do not do it. Ask.

OUTPUT
Reply in plain English, at most two to four short paragraphs. End with a
single sentence stating what action you took or will take next.

The strength of this structure — every section has a single intent. Add a tool? Only CAPABILITIES changes. Add a restriction? Only RULES changes. The prompt is maintainable English.

4.2 Anti-patterns in system prompts

Anti-pattern 1 — example flood. First-time authors cram in ten or twenty examples. Anthropic recommends the opposite — "three to five diverse, canonical examples" beat fifty inconsistent ones. Too many examples cause overfitting; the agent loses the ability to generalize.

Anti-pattern 2 — adjective parade. "Be helpful, professional, friendly, concise, accurate, thoughtful, careful." Seven adjectives weaken each other. Pick two — "Direct and concise. No filler." — and define them precisely.

Anti-pattern 3 — meta-instructions. "Think carefully before answering." Meaningful to a human, mostly noise to an agent. Either prescribe the actual reasoning steps ("Think step by step about X") or leave it out.

4.3 System message vs user message

Where you put the English matters. Rules that hold for the whole session live in the system prompt. Information specific to one request lives in the user message.

Before — everything in the system prompt:

You are a code reviewer. The user is reviewing PR #1234, which adds a new
billing flow. The PR description is: "..."

The problem — the next PR needs a brand new system prompt.

After — separated:

SYSTEM
You are a code reviewer for this monorepo. Focus on correctness, security,
and consistency with the patterns in src/lib/. Do not comment on style — a
linter handles that.

USER
Review PR #1234. The diff is below. The author claims it adds a new billing
flow.
[diff]

System prompt: reusable. User message: changes every time. Clean separation.

5. RFCs and design docs — written for humans and agents

RFCs and design docs are the high-water mark of technical English. In 2026, their audience now includes agents, which take an RFC, split it into work items, and sometimes execute the safe ones themselves.

5.1 Where traditional RFCs fall short

A traditional RFC often has these traits:

• Leaves the how vague — out of respect for the implementer's autonomy
• Scatters the why across the body — humans synthesize as they read
• States non-functional requirements loosely — "should be fast enough"
• Mentions alternatives briefly — "we considered X but decided not to"

All of this is fine for a human, but an agent cannot extract clear, actionable work units from this kind of RFC.

5.2 A new structure for RFCs read by agents too

1. TL;DR (1 paragraph)         — human reads it in 30 seconds
2. Problem                     — why we are doing this now
3. Goals / non-goals           — explicit boundaries
4. Proposal                    — what we will build
5. Detailed design             — how we will build it
6. Alternatives considered     — why we did not take other paths
7. Open questions              — what is still undecided
8. Work breakdown (NEW)        — actionable work units
9. Acceptance criteria (NEW)   — definition of done
10. Non-functional requirements (latency, throughput, error budget — in numbers)

Two new sections compared to a traditional RFC — Work breakdown and Acceptance criteria. Both should be written so an agent can use them as a starting point for action.

Before — a vague work breakdown:

We will need to update the API, the frontend, and add some tests.

After — an actionable work breakdown:

1. Add POST /v2/billing/preview endpoint
   - Request: BillingPreviewRequest (new schema)
   - Response: BillingPreviewResponse
   - Backed by services.billing.preview()
   - File: services/billing/handlers/preview.ts (new)
   - Estimated diff: ~150 lines

2. Add usePreview hook
   - File: src/hooks/usePreview.ts (new)
   - Wraps the new endpoint with TanStack Query
   - Estimated diff: ~40 lines

3. Wire the hook into BillingScreen
   - File: src/screens/BillingScreen.tsx (modify)
   - Loading and error states required
   - Estimated diff: ~80 lines

4. Tests
   - Unit: services/billing/preview.test.ts
   - Integration: e2e/billing/preview.spec.ts

The difference is simple — each item (a) starts with a verb, (b) points at a specific file, (c) sizes itself. Humans review better, and agents can act on it directly.

5.3 Non-functional requirements in numbers

This was always good practice, but it matters more in the agent era.

Before:

The new endpoint should be fast. It should handle our peak traffic.

After:

- p99 latency under 200 ms at 500 requests per second.
- Error rate under 0.5 percent over any 5 minute window.
- The endpoint must not push upstream Postgres CPU above 60 percent during
  peak — current peak is 38 percent.
- If the endpoint fails for more than 30 seconds, fall back to the existing
  billing summary endpoint (graceful degradation).

Numbers let humans review, and they give an agent a concrete target to test against.

6. Issues and tickets — descriptions an agent can act on

Ticket-based agents like Devin, Codex Cloud, and GitHub Copilot Workspace are now standard. The way you write a ticket is now the way you shape an agent's work.

6.1 A ticket for a human vs a ticket for an agent

A typical ticket aimed at a human developer:

Title: Login form looks broken on mobile

Description: Hey, when I try to log in on my phone, the form looks weird.
The button is cut off and I can't really submit. Can you take a look?

A human developer picks up this ticket — pulls out their phone, reproduces it, asks the designer about intent, searches for related issues, and starts work. An agent given this ticket alone can do almost nothing.

The same problem, rewritten for an agent:

Title: LoginForm submit button truncated on mobile viewport

Reproduction
1. Open http://localhost:3000/login in Chrome
2. Open DevTools and select the "iPhone 14 Pro" viewport (393x852)
3. Observe that the submit button extends past the right edge of the form
4. Expected: the submit button is fully visible and aligned to the form's right edge

Suspected cause
The form container has `max-width: 400px`, but at viewports under 400px
plus the form's padding, content overflows. See `src/components/LoginForm.tsx`
around line 45.

Acceptance criteria
- The submit button is fully visible at all viewports 320 px wide and above
- No visual regression on desktop (1024 px and above)
- The existing Playwright login test still passes

Out of scope
- Do not redesign the form
- Do not change the button text or color
- Do not touch the OAuth button — it is being redone in #1240

It looks longer, but the agent can start immediately, and when a human reviews the result they can see exactly what was and was not in scope. The Out of scope section is the secret weapon. The most common agent mistake is "cleaned the street and then also cleaned the neighbor's yard." Spelling out the edges prevents it.

6.2 A ticket template

A template usable across a team:

## Context
(1-3 sentences — why this matters now)

## Reproduction or scenario
(numbered steps for bugs; a concrete user story for features)

## Acceptance criteria
- ...
- ...

## Out of scope
- ...

## Related
- linked issues, ADRs, RFCs

Out of scope is the new addition. What used to be implicit for a human developer must be explicit for an agent.

7. Commit messages and PR descriptions — AI-first workflow

Commit messages and PR descriptions are the English we write most often, and they are the English agents read most often — and increasingly, write most often.

7.1 A good commit message (Conventional Commits plus the why)

Before:

fix bug

After:

fix(billing): prevent double-charge when retry follows a partial failure

The retry path was not idempotent because we generated a new idempotency
key on every attempt. We now reuse the key for the whole transaction
attempt, scoped to the user and order id.

Repro: tests/billing/retry.test.ts::"survives partial gateway failure"

Three elements — (1) type(scope): summary, (2) a paragraph of why, (3) a reproduction or test pointer. Humans like it, and the next agent that touches this area thanks you.

7.2 AI-written PR descriptions vs human-written ones

PR descriptions auto-generated by AI have a few common weaknesses.

• They list every changed line in sequence ("Updated A, B, C")
• They almost never explain why
• They treat all changes as equal — no separation of headline vs detail

A good PR description, whether a human writes it briefly or an agent writes it at length, has:

## What
(1-2 paragraphs — what changes, in business terms)

## Why
(why now, why this approach)

## How (only if non-obvious)
(design choices that the code does not reveal)

## Risks
(what could break, how you looked)

## Test plan
(how you verified — commands run, screens seen, logs read)

When you ask an agent to generate a PR description, explicitly require these five sections. The result is dramatically better.

7.3 Co-authored-by and honesty

Marking AI-assisted code honestly is both ethical and practical. Co-Authored-By: Claude on a commit becomes a signal months later — "this was first drafted by an agent, then reviewed by me." When you debug the same area in six months, that signal carries real value.

8. Prompt writing as a craft

By now one pattern should be clear. Writing English for agents is, at its core, the same as writing good technical English. A person who writes clean RFCs writes clean system prompts, and vice versa.

8.1 General principles for good English — agent-era version

Principle 1 — one intent per paragraph. Humans appreciate it; agents need it. Mix a command with an exception and a tone in one paragraph and everyone struggles.

Principle 2 — explicit context. "As discussed yesterday" is explicit to a colleague and blank to an agent. Either restate the context every time, or — better — put it in a permanent document.

Principle 3 — named constraints. Not "this should be fast" — write "p99 under 200 ms". Not "secure" — write "no plaintext credentials in logs." Named constraints are verifiable.

Principle 4 — define conflict behavior. Good English always includes "if X conflicts with Y, do Z." If the conflict is not addressed, the agent picks one arbitrarily, and the pick is often wrong.

Principle 5 — concrete examples. Three canonical examples outperform one abstract rule. But — your examples must be internally consistent.

8.2 How to make writing shorter

AGENTS.md and system prompts are stronger when shorter. Five techniques.

1. Drop intensifiers: "very", "really", "quite", "somewhat" — almost always cut them
2. Un-nominalize: not "perform a review of" — just "review"
3. Active over passive: not "tests are to be written" — "write tests"
4. One command per bullet: if a bullet contains two commands, split it
5. Remove repetition: if the same rule appears twice, delete one or rewrite the second to address a different angle

A good system prompt is like a good poem — pulling any single word weakens the meaning.

8.3 Curating canonical examples

Anthropic recommends "three diverse, canonical examples." The word canonical is doing work. An example is not just something that compiles — it should represent "how our team works." Off-tone examples generalize into off-tone behavior.

Checklist for a canonical example:

• The intent of the change is clear
• The code style matches your team's median
• It addresses one edge case (no edge case is too simple; many is noise)
• It is a generalizable pattern

9. Politeness vs directness — the trade-off

To native English speakers, directness can read as rudeness. "Do this" feels harsh next to "Could you do this." But in writing meant for agents, that politeness becomes cost.

9.1 Serving both audiences

AGENTS.md is read by both humans and agents. Too direct, and humans feel the team is cold. Too polite, and the agent treats it as noise. There is a middle.

Before — cold tone:

Do not delete files. Do not modify generated code. Do not add dependencies.

After — clear but warm:

Working with this repo:
- Files are precious — we prefer marking unused files in a summary over deleting them.
- Generated code lives in `src/generated/` — it is regenerated by CI, so do not edit by hand.
- Dependencies are tracked carefully — please ask before adding a new one. The bundle is at 280 KB and growing.

Same commands, but (1) a short why for each, and (2) "we" and "please" preserve a human register. The agent still follows the commands precisely, and humans enjoy reading it.

9.2 The tone of automated messages

Auto-generated PR comments. Standup-bot messages. The English in these automated messages defines team culture more than people realize. "Failed" and "This pull request did not pass the required checks" are the same information, but the second one is human. In the agent era, time spent on the English in automated messages is unusually well spent.

9.3 The myth that weak English is polite

"Could you maybe consider possibly trying to..." is not polite — it is uncertain. Writing coaches have been teaching this for decades, and the agent era is bringing it back: clarity is the highest form of courtesy. Saving the reader — human or agent — from having to guess is the real consideration.

Epilogue — How to write the English agents will read

Checklist — before you ship an AGENTS.md or system prompt

• I named the audience — humans, agents, or both
• For each line, I asked, "would the agent have made a mistake without this?"
• I removed hedges (probably, perhaps, kind of, somewhat)
• I wrote non-functional requirements in numbers (latency, throughput, error rate)
• Every important rule has a conflict definition: "if X conflicts with Y, do Z"
• There is an Out of scope or Boundaries section
• There are three or fewer examples, all matching team standards
• The document is short — a reader finishes it in 30 seconds
• Politeness comes from a short why, not from hedging

Anti-patterns and what to do instead

One-line summary

Good developer English in 2026 lets a human and an agent both read it in 30 seconds and arrive at the same action.

What is next

This post focused on one natural language — English — facing both human and agent readers. The next post moves down one layer to the interface that English calls into: tools, MCP (Model Context Protocol), and the craft of writing tool descriptions. A well-written tool description reads like a well-typed function signature, and the same weak English that breaks system prompts also breaks tools. That post is the natural sequel.

If you want to become a stronger English writer as a developer, the fastest path is to spend less time on English aimed at colleagues and more time on the English that agents read. That is where the shape of your work begins to change.

References

• agents.md — open format for guiding coding agents
• Custom instructions with AGENTS.md — OpenAI Codex Developers
• openai/codex — AGENTS.md (repository)
• Best practices for Claude Code — Anthropic Docs
• Writing a good CLAUDE.md — HumanLayer Blog
• How Anthropic teams use Claude Code (PDF)
• Effective context engineering for AI agents — Anthropic Engineering
• Writing effective tools for AI agents — Anthropic Engineering
• Prompting best practices — Claude API Docs
• Use examples (multishot prompting) — Anthropic Docs
• How to Write a Good Spec for AI Agents — O'Reilly Radar
• How to write a good spec for AI agents — Addy Osmani
• How to Build Your AGENTS.md (2026) — Augment Code
• Guides: AI Coding Agents — Next.js Docs
• Optimizing technical documentations for LLMs — DEV Community
• Write LLM-friendly docs — Fern
• OpenAI co-founds the Agentic AI Foundation under the Linux Foundation
• Anthropic's Interactive Prompt Engineering Tutorial — GitHub