사용 중인 AI 코딩 에이전트의 컨텍스트 파일 정리

최근에는 작업 내용에 따라 Codex, Claude Code, Kiro, Gemini CLI를 전환하며 사용하고 있습니다.

각 에이전트의 컨텍스트 (Context) 파일에는 공통된 것도 있고, 툴 고유의 것도 있습니다. 잊어버리기 쉬우므로 한 번 정리해 둡니다.

컨텍스트 파일 목록

에이전트	Context file 명	프로젝트 내 표준 배치	AGENTS.md 취급	설명 페이지
Codex	AGENTS.md	./AGENTS.md	Native	AGENTS.md를 사용한 Custom instructions
Claude Code	CLAUDE.md	./CLAUDE.md	@AGENTS.md로 import	How Claude remembers your project
Gemini CLI	GEMINI.md	./GEMINI.md	context.fileName으로 지정	Provide context with GEMINI.md files
Kiro	Steering files	./.kiro/steering/*.md	AGENTS.md도 읽음	Steering
GitHub Copilot	copilot-instructions.md	./.github/copilot-instructions.md	AGENTS.md도 읽음	Adding repository custom instructions

계층 구조 대응

global -> project root -> subfolder

와 같은 계층 구조는 많은 툴에서 어떤 형태로든 지원하고 있습니다. 다만, 모든 툴이 각 계층에 동일한 파일명을 배치하는 방식은 아닙니다.

Codex

• Global:
  ~/.codex/AGENTS.md

• Project root:
  ./AGENTS.md

• Subfolder:
  ./subdir/AGENTS.md

Claude Code

• Global:
  ~/.claude/CLAUDE.md

• Project root:
  ./CLAUDE.md

or ./.claude/CLAUDE.md

• Subfolder:
  ./subdir/CLAUDE.md

/ .claude/rules/*.md

Gemini CLI

• Global:
  ~/.gemini/GEMINI.md

• Project root:
  ./GEMINI.md

• Subfolder:
  ./subdir/GEMINI.md

Kiro

• Global:
  ~/.kiro/steering/*.md

• Project root:
  ./.kiro/steering/*.md

• Path-specific:
  fileMatch

/ manual

/ auto

inclusion

GitHub Copilot

• Global: Personal / organization instructions

• Project root:
  ./.github/copilot-instructions.md

• Path-specific:
  ./.github/instructions/*.instructions.md

/ AGENTS.md

보충: Kiro의 steering files

Kiro에서는 프로젝트 지시사항을 steering files라고 부릅니다. 다른 툴과는 달리 여러 파일로 나누어 관리할 수 있습니다.

워크스페이스 단위의 steering files는 다음 위치에 둡니다.

.kiro/steering/*.md

글로벌 steering files는 다음 위치입니다.

~/.kiro/steering/*.md

기본적인 steering files로는 다음 3가지가 준비되어 있습니다.

.kiro/steering/product.md
.kiro/steering/tech.md
.kiro/steering/structure.md

각각 제품의 목적, 기술 스택 (tech stack), 프로젝트 구조를 설명하는 파일입니다.

또한, steering files에는 읽기 타이밍을 지정하는 inclusion mode가 있습니다.

---
inclusion: always
---

---
inclusion: fileMatch
fileMatchPattern: "**/*.tsx"
...

---
inclusion: manual
---

---
inclusion: auto
name: api-design
...

AGENTS.md의 위치

에이전트용 컨텍스트 파일에는 아직 공식적으로 통일된 공통 표준이 없습니다. 하지만 AGENTS.md와 같이 AGENTS.md를 공통 지시 파일로 취급하려는 움직임이 있습니다.

Discussion