프롬프트 주입 시스템
AI 에이전트에게 시스템 지침과 작업 맥락을 자동으로 전달하는 시스템입니다.
개요
기존의 inject/ 폴더 방식은 AGENTS.*.md 계층 시스템으로 대체되었습니다. make claude 실행 시 CLI가 --append-system-prompt 파라미터로 자동 주입합니다.
주입 계층
/AGENTS.SYSTEM.md ← 전역 시스템 규칙
/AGENTS.USER.md ← 전역 작업 맥락
↓ 병합
{project}/AGENTS.SYSTEM.md ← 프로젝트 시스템 규칙
{project}/AGENTS.USER.md ← 프로젝트 작업 맥락
↓ 병합
.claude/AGENTS.SYSTEM.md ← Claude 어댑터 규칙
↓ 병합
user-prompt-submit.sh 동적 주입 ← 세션 요약, 환경 정보
| 순서 | 코드 | 파일 | 역할 | 주입 대상 |
|---|---|---|---|---|
| 1 | GS | /AGENTS.SYSTEM.md | 전역 시스템 프롬프트 | Claude + 외부 LLM |
| 1 | GU | /AGENTS.USER.md | 전역 작업 맥락 | Claude + 외부 LLM |
| 2 | PS | {project}/AGENTS.SYSTEM.md | 프로젝트별 규칙 | Claude + 외부 LLM |
| 2 | PU | {project}/AGENTS.USER.md | 프로젝트별 맥락 | Claude + 외부 LLM |
| 3 | IS | .claude/AGENTS.SYSTEM.md | 어댑터 규칙 | Claude만 |
주입 방식
CLI 주입 (시스템 프롬프트)
make claude가 AGENTS.SYSTEM.md 파일들을 읽어서 --append-system-prompt로 전달합니다:
# ops/makefile/claude.mk에서 자동 처리
claude --append-system-prompt "$(cat AGENTS.SYSTEM.md)"
이 방식으로 주입된 내용은 AI가 파일을 별도로 Read할 필요 없이 시스템 프롬프트에 직접 포함됩니다.
Hook 주입 (동적 컨텍스트)
user-prompt-submit.sh가 매 프롬프트마다 동적으로 주입합니다:
| 주입 내용 | 소스 |
|---|---|
| 환경 정보 (Git, Docker) | git status, docker ps |
| 세션 요약 | .ai-core/data/context/summaries/ |
| AGENTS.USER.md | 프로젝트 작업 맥락 |
| 프로젝트 Memory 목록 | .ai-core/data/memory/ |
| Multi-LLM 의견 | chorus/consensus 응답 |
| 프롬프트 주입 상태 (PI) | 계층별 토큰 수 |
프롬프트 컨텍스트 템플릿
.ai-core/prompt-context/ 폴더에 템플릿이 있습니다:
.ai-core/prompt-context/
├── 001-environment.md # 환경 정보 (Git, Docker)
├── 002-project-context.md # 프로젝트 컨텍스트
├── 003-checklist-status.md # 체크리스트 상태
└── 004-multi-llm-opinions.md # Multi-LLM 의견
user-prompt-submit.sh가 {{VARIABLE}} 플레이스홀더를 실제 값으로 치환합니다.
tmux 상태바에서 확인
2줄 우측에 PI(Prompt Injection) 상태가 표시됩니다:
GS(3470) GU(53) PS(76) PU PP
| 코드 | 의미 | 소스 |
|---|---|---|
| GS | Global System | /AGENTS.SYSTEM.md |
| GU | Global User | /AGENTS.USER.md |
| PS | Project System | {project}/AGENTS.SYSTEM.md |
| PU | Project User | {project}/AGENTS.USER.md |
| PP | Profile Prompt | (삭제됨) |
숫자는 주입된 토큰 수. 어떤 지침이 적용 중인지 한눈에 파악 가능합니다.
SYSTEM vs USER 구분
| 구분 | AGENTS.SYSTEM.md | AGENTS.USER.md |
|---|---|---|
| 내용 | 규칙, 금지사항, 원칙 | 작업 맥락, 진행 상황 |
| 변경 빈도 | 드물게 | 자주 |
| 예시 | "DB 삭제 명령 금지" | "현재 v2.1.0 작업 중" |
| 주입 방식 | CLI --append-system-prompt | Hook user-prompt-submit.sh |
Consensus용 주입
/-consensus 실행 시 외부 LLM에만 추가 주입되는 파일:
| 파일 | 역할 |
|---|---|
/AGENTS.CONSENSUS.md | 전역 consensus 지침 |
{project}/AGENTS.CONSENSUS.md | 프로젝트별 consensus 지침 |
Claude 자체에는 주입되지 않고, 외부 LLM(OpenCode, Kilo, Codex, Gemini)에만 전달됩니다.
기존 inject/ 폴더와의 대응
| 기존 (.claude/config/inject/) | 현재 (AGENTS.*.md) |
|---|---|
inject/global.md | /AGENTS.SYSTEM.md |
inject/claude.md | .claude/AGENTS.SYSTEM.md |
inject/workspace/*.md | workspace/{project}/AGENTS.SYSTEM.md |
inject/sessions/*.md | user-prompt-submit.sh 동적 주입 |
기존 inject/ 폴더의 내용은 해당하는 AGENTS.*.md 파일로 옮기면 됩니다. frontmatter(enabled, repeat, expires)는 더 이상 필요하지 않습니다.
make claude 명령과의 관계
시스템 프롬프트 주입은 make claude 실행 시 run_claude 함수가 담당합니다. 4개 명령 변형(claude/claude-auto/claude-resume/claude-resume-auto)이 있으며, 모두 동일한 주입 로직을 공유합니다.
자세한 내용은 make claude 명령 체계를 참고하세요.
다음 단계
- make claude 명령 체계 — 4개 명령, Auto 모드, Alias
- 프로젝트 Memory — 축적 지식 목록 주입
- 설정 시스템 — global/detail 설정
- Hooks — hook 실행 흐름
- tmux 연동 — 상태바에서 PI 확인