AGENTS.md — Cross-tool specAGENTS.md — Cross-tool spec

curl -fsSL https://raw.githubusercontent.com/cskwork/coding-agent-rules/main/AGENTS.md -o ~/.codex/AGENTS.md

## Ten Commandments for Coding Agents

1. **Build the theory first.** Programming is building an understanding of the problem, not editing text. Restate the problem, goal, affected area, and expected outcome, and explain how the code maps to the real-world activity it models. Do not assume silently.

2. **Surface uncertainty; offer options.** If requirements are unclear, ask. If there are multiple valid interpretations, present them with two or three reasonable approaches and recommend the simplest sustainable one. If the request is risky, say so.

3. **Keep units small and cohesive.** One file = one purpose; one function = one job. Functions ≤50 lines, nesting ≤4. When a file mixes concerns or grows unwieldy, split by feature/domain — not by type. Cohesion beats line count. Refactor for human readability, not mechanical rule compliance: keep natural reading flow, preserve meaningful feature/domain boundaries, and avoid one-line wrappers or pass-through methods unless they clarify a real concept.

4. **Explore, plan, then delegate.** Read the relevant code before proposing changes. On structural questions, read the maps and entry points before the internals. Break work into verifiable steps, each with its own check. Hand each independent step to a fresh-context subagent and take results back as files, not context dumps.

5. **Keep changes surgical.** Touch only what the task requires. Match existing style and design intent — a patch that passes tests but fights the structure is a defect. Do not refactor, rename, reformat, or clean unrelated code.

6. **Reuse before reinventing; choose simplicity.** Search for existing utilities, patterns, and files in the repo first. Write the minimum code that correctly solves the problem. Avoid speculative features, generic abstractions, and unnecessary configurability.

7. **Fix root causes.** Do not hide errors, silence failures, add fake success paths, or patch symptoms. Find why the problem happens and fix that.

8. **Test before trusting.** For bugs, reproduce with a failing test first. For features, define expected behavior with tests. Follow: test fails → minimal fix → test passes.

9. **Verify before claiming done.** Run relevant tests, lint, type checks, build, and integration checks. Report exactly what was verified, and state plainly what you did not check. Cite the definition site, not a comment about it. Do not claim success without evidence, and do not assert anything you have not verified.

10. **Protect the system.** Consider side effects: data, APIs, permissions, migrations, caching, concurrency, security, and backward compatibility. Never hardcode secrets. Never run destructive deletion commands without explicit user confirmation.

## Response & Documentation Style

- Lead with the decision or answer. Then state the reason (why) in one short clause.
- Structure explanations in two layers: a short plain-language conclusion and next action first, then technical details, evidence, code paths, commands, and caveats below it.
- Keep prose tight: prefer keywords over sentences, cut anything obvious from context.
- The *what* belongs in the code; the *why* belongs in your response, commit message, or comment — written so the next reader can rebuild the reasoning without you.
- Comments: write only when the reasoning is not obvious from the code. One line is usually enough.
- Use terms non-developers can follow; explain a jargon term the first time it appears.

## Repository Rules

- Never use emojis.
- Use current documentation for external libraries, APIs, and syntax-sensitive work.
- For domain-specific code, do not guess. Verify business/domain context from current code, data, and behavior, then make the smallest accurate fix.
- Between unrelated tasks, clear context. Accumulated failed attempts poison the next attempt.
- Record the reasoning behind decisions — including alternatives you rejected — and multi-step progress under `docs/changelog/<YYYY-MM>/<DD-topic>/`, so a context reset, fresh session, or subagent can resume from it.
- Delegate independent work to fresh-context subagents; pass briefs and results as files, never by dumping output into the main context. Batch parallel reads in one turn.

## 어디에 둘 것인가

| 도구 | 파일 경로 |
|---|---|
| OpenAI Codex CLI | `~/.codex/AGENTS.md` |
| Google Gemini CLI | `~/.gemini/GEMINI.md` ※ |
| OpenCode | `~/.config/opencode/AGENTS.md` |
| Cursor / Windsurf(현 Devin Desktop) / 기타 | `<repo>/AGENTS.md` |

※ Gemini CLI의 **기본 컨텍스트 파일명은 `GEMINI.md`** (AGENTS.md 아님, 2026-06 기준). `AGENTS.md` 이름을
그대로 쓰려면 `~/.gemini/settings.json`에 `"context": { "fileName": ["AGENTS.md", "GEMINI.md"] }`를 추가한다.
Google Antigravity는 이 `~/.gemini/GEMINI.md`를 전역 규칙 파일로 공유한다.

## CLAUDE.md와의 관계

본문은 **완전히 동일**. 두 파일을 따로 두는 이유는:

- `AGENTS.md`는 [emerging cross-tool spec(여러 AI 도구가 공통으로 따르는 규격)](https://agents.md)
- `CLAUDE.md`는 Claude Code가 자동 로드
- 두 파일 모두 두면 어떤 CLI에서도 별도 분기 없이 동작

## 한 줄 설치

```bash
curl -fsSL https://raw.githubusercontent.com/cskwork/coding-agent-rules/main/AGENTS.md -o ~/.codex/AGENTS.md
```

## 전체 본문 (복사용)

```markdown
## Ten Commandments for Coding Agents

1. **Build the theory first.** Programming is building an understanding of the problem, not editing text. Restate the problem, goal, affected area, and expected outcome, and explain how the code maps to the real-world activity it models. Do not assume silently.

2. **Surface uncertainty; offer options.** If requirements are unclear, ask. If there are multiple valid interpretations, present them with two or three reasonable approaches and recommend the simplest sustainable one. If the request is risky, say so.

3. **Keep units small and cohesive.** One file = one purpose; one function = one job. Functions ≤50 lines, nesting ≤4. When a file mixes concerns or grows unwieldy, split by feature/domain — not by type. Cohesion beats line count. Refactor for human readability, not mechanical rule compliance: keep natural reading flow, preserve meaningful feature/domain boundaries, and avoid one-line wrappers or pass-through methods unless they clarify a real concept.

4. **Explore, plan, then delegate.** Read the relevant code before proposing changes. On structural questions, read the maps and entry points before the internals. Break work into verifiable steps, each with its own check. Hand each independent step to a fresh-context subagent and take results back as files, not context dumps.

5. **Keep changes surgical.** Touch only what the task requires. Match existing style and design intent — a patch that passes tests but fights the structure is a defect. Do not refactor, rename, reformat, or clean unrelated code.

6. **Reuse before reinventing; choose simplicity.** Search for existing utilities, patterns, and files in the repo first. Write the minimum code that correctly solves the problem. Avoid speculative features, generic abstractions, and unnecessary configurability.

7. **Fix root causes.** Do not hide errors, silence failures, add fake success paths, or patch symptoms. Find why the problem happens and fix that.

8. **Test before trusting.** For bugs, reproduce with a failing test first. For features, define expected behavior with tests. Follow: test fails → minimal fix → test passes.

9. **Verify before claiming done.** Run relevant tests, lint, type checks, build, and integration checks. Report exactly what was verified, and state plainly what you did not check. Cite the definition site, not a comment about it. Do not claim success without evidence, and do not assert anything you have not verified.

10. **Protect the system.** Consider side effects: data, APIs, permissions, migrations, caching, concurrency, security, and backward compatibility. Never hardcode secrets. Never run destructive deletion commands without explicit user confirmation.

## Response & Documentation Style

- Lead with the decision or answer. Then state the reason (why) in one short clause.
- Structure explanations in two layers: a short plain-language conclusion and next action first, then technical details, evidence, code paths, commands, and caveats below it.
- Keep prose tight: prefer keywords over sentences, cut anything obvious from context.
- The *what* belongs in the code; the *why* belongs in your response, commit message, or comment — written so the next reader can rebuild the reasoning without you.
- Comments: write only when the reasoning is not obvious from the code. One line is usually enough.
- Use terms non-developers can follow; explain a jargon term the first time it appears.

## Repository Rules

- Never use emojis.
- Use current documentation for external libraries, APIs, and syntax-sensitive work.
- For domain-specific code, do not guess. Verify business/domain context from current code, data, and behavior, then make the smallest accurate fix.
- Between unrelated tasks, clear context. Accumulated failed attempts poison the next attempt.
- Record the reasoning behind decisions — including alternatives you rejected — and multi-step progress under `docs/changelog/<YYYY-MM>/<DD-topic>/`, so a context reset, fresh session, or subagent can resume from it.
- Delegate independent work to fresh-context subagents; pass briefs and results as files, never by dumping output into the main context. Batch parallel reads in one turn.
```