엔지니어링 블로그
ENGLISH 한국어

adr-index-skill

adr-index: Keeping AGENTS.md Small with ADRs + a Lightweight Index

요즘 Codex / Claude Code / Gemini 같은 AI 코딩 도구를 제대로 써보니, 의외로 빨리 부딪히는 문제가 하나 있었습니다.

AGENTS.md(또는 비슷한 에이전트 지침 파일)가 점점 커진다는 것.

처음에는 편해서 이것저것 다 적습니다.

  • 지금 무엇을 하고 있는지
  • 어떤 결정을 내렸는지
  • 나중에 참고할 내용
  • 완료된 작업들

그런데 프로젝트가 커질수록 AGENTS.md는:

  • 컨텍스트를 계속 잡아먹고(= 토큰 낭비)
  • 과거 기록이 섞여서 잡음이 늘고
  • 에이전트가 핵심을 놓치기 쉬워지고
  • 결국 “유지보수 대상”이 됩니다

그래서 방향을 바꿨습니다.

  • AGENTS.md는 ‘현재 규칙 + 현재 컨텍스트’만
  • 결정은 ADR(Architecture Decision Record)로 분리
  • 에이전트가 ADR을 매번 전체 검색하지 않도록 가벼운 index.json을 생성

이 흐름을 도와주는 스킬이 adr-index입니다.

문제: 완료 로그가 쌓이면 AGENTS.md가 망가진다

AGENTS.md에 완료 로그를 계속 쌓는 방식은, 시간이 지날수록 이득보다 손해가 커집니다.

  1. 컨텍스트 비용 증가
  • AGENTS.md가 커질수록 에이전트가 매번 읽어야 할 텍스트가 늘어납니다.
  1. 잡음 증가
  • 과거 결정/완료 항목이 많아질수록 “지금 중요한 것”이 가려집니다.
  1. 유지보수 부담
  • 규칙 문서였던 AGENTS.md가 ‘위키/로그’가 되어버리고, 결국 정리가 필요해집니다.

결국 AGENTS.md는 “누적형 문서”가 아니라 휘발되어야 하는 문서에 가깝습니다.

해결: 결정을 ADR로 남기고, 에이전트는 인덱스만 본다

여기서 핵심은 “히스토리를 버리자”가 아니라,

  • 히스토리(결정)는 ADR로 남기고
  • 찾기 쉽게 작은 인덱스(index.json)로 정리

하는 것입니다.

ADR에 남기면 좋은 것

  • 왜 이 결정을 했는지 (Context)
  • 무엇을 선택했는지 (Decision)
  • 무엇이 달라지는지/대가(trade-off)는 무엇인지 (Consequences)

ADR에 굳이 안 남겨도 되는 것

  • 시행착오 로그
  • 디버깅 과정
  • 커밋 내역 나열
  • 단순 구현 체크리스트

adr-index가 하는 일 (기술적으로)

adr-index는 RAG/임베딩 없이, 아주 단순한 방식으로 “결정 인덱스”를 만듭니다.

  • 입력: docs/adr/*.md
  • 출력: docs/adr/index.json

1) ADR 상단 메타만 스캔

ADR 전체를 읽지 않고, 파일 상단 일부(예: 60줄)만 읽습니다.

이유:

  • 빨라야 하고
  • 잡음을 줄여야 하고
  • 인덱스는 항상 결정적으로(deterministic) 생성되어야 하니까요.

2) 헤더 형식 검증

ADR 파일 첫 줄은 아래 형식이어야 합니다.

  • # ADR-YYYYMMDD-####-XXX: <title>

예:

  • # ADR-20260203-0007-A9F: Use JSONB for event payload storage

이 포맷을 쓰면:

  • 날짜 기준 정렬이 자연스럽고
  • 같은 날 여러 ADR을 작성해도 충돌이 줄고
  • 병렬 작업에도 안전합니다.

3) 메타데이터 파싱

상단에 있으면 읽고, 없으면 빈 값으로 둡니다.

  • Tags:
  • Status: (Proposed | Accepted | Deprecated)
  • Date: (YYYY-MM-DD)
  • TL;DR:

4) 비-ADR 파일은 제외

docs/adr/README.md, 템플릿 같은 파일은 인덱싱 대상에서 제외합니다.

5) 인덱스 생성

docs/adr/index.json에 아래 필드만 저장합니다.

  • id
  • title
  • tags (list)
  • status
  • date
  • tldr
  • path

유니코드(한글)도 보존해서 diff가 깨끗하게 나옵니다.

워크플로: 언제 실행해야 하나?

정리하면 “ADR이 바뀌었을 때”만 실행하면 됩니다.

권장 타이밍

  • ADR 추가/수정 직후
  • git commit 전에 (ADR + index.json을 같이 커밋)
  • PR 올리기 직전 (팀 작업이라면)

실행 명령

  • Codex CLI: $adr-index
  • Claude Code / Gemini CLI: /adr-index

AGENTS.md는 어떻게 관리하나?

핵심 규칙은 간단합니다.

  • AGENTS.md에는 완료 목록을 누적하지 않는다
  • 결정은 ADR에 남긴다
  • AGENTS.md에는 링크/짧은 요약만 남긴다(필요하면)

예를 들어,

  • 작업 도중: AGENTS.md에 “현재 작업”이 있을 수 있음
  • 결정 확정: ADR 작성
  • adr-index 실행: index.json 갱신
  • 작업 완료: AGENTS.md에서 완료 항목 제거 (또는 ADR 링크만 남김)

AGENTS.md는 이렇게 “자연스럽게 가벼워지는” 게 정상입니다.

ADR이 필요한지 판단하는 빠른 규칙

아래 중 하나라도 해당하면 ADR을 쓰는 쪽이 보통 이득입니다.

  • 대안을 비교하고 하나를 선택했다
  • 이후 작업에 제약을 만든다
  • 나중에 되돌리기 어렵다
  • 코드만 봐서는 ‘왜’가 명확하지 않다
  • AGENTS.md에 적고 싶은 유혹이 든다

애매하면 ADR을 쓰는 편이 대체로 싸게 먹힙니다.

오픈소스 공개: adr-index v0.1.0

작고 단순하지만, “AGENTS.md 비대화” 문제를 해결 할 것으로 기대하고 있습니다.

  • 결정은 ADR로 남고
  • 에이전트는 index.json만 보고 필요한 ADR만 열고
  • 토큰을 아끼면서도 맥락은 잃지 않습니다.

레포:

AI가 스스로 ‘이건 ADR 필요’라고 말하게 만드는 방법

아래는 GPT-5.2와 함께 정리한 내용입니다.

“AI가 스스로 이건 ADR이 필요해요라고 말하게 만드는 방법”은 프롬프트 트릭이 아니라 역할 설계 문제입니다.

아래는 실제로 잘 먹히는 방식으로 정리했어요.

⸻

AI가 스스로

“이건 ADR이 필요합니다”라고 말하게 만드는 방법

핵심 결론부터:

❌ “ADR이 필요하면 말해줘”라고 시키면 안 됩니다 ✅ AI에게 ‘ADR을 요구할 권한’이 아니라 ‘ADR 판단 책임’을 준다

⸻

1️⃣ 가장 중요한 전제: AI는 “결정”을 감지할 수 있다

AI는 생각보다 잘 압니다. • 지금 이게 단순 구현인지 • 설계 판단이 개입됐는지 • 되돌리기 어려운 선택인지

문제는 그걸 말할 자리가 없다는 것이에요.

그래서 우리는 AI에게 이 역할을 줍니다:

“나는 지금 구현자가 아니라, 결정 감시자(decision sentinel)다.”

⸻

2️⃣ AGENTS.md에 넣을 단 하나의 규칙

이걸 AGENTS.md에 넣어두면, 효과가 큽니다.

ADR Detection Rule

If you make or rely on a decision that:

  • introduces architectural constraints,
  • involves trade-offs,
  • or is not obvious from code alone,

you MUST pause and explicitly state: “An ADR is required for this decision.”

포인트: • “may” ❌ • “MUST” ⭕ • 행동이 아니라 발화(say it) 를 강제

⸻

3️⃣ AI의 정상적인 행동 흐름 (이상적인 상태)

AI가 이렇게 말하면 성공입니다 👇

“This change introduces a new constraint on error handling. An ADR is required before proceeding.”

또는 작업 도중:

“Before implementing this, an ADR should be written to capture the decision.”

중요한 건: • 작업을 멈춘다 • 사람에게 판단을 넘긴다

이건 AI에게 굉장히 자연스러운 행동입니다.

⸻

4️⃣ 절대 시키면 안 되는 말

아래는 효과 없습니다. • “ADR이 필요하면 알아서 만들어” • “ADR 필요 여부 판단해” • “ADR 작성해도 될까?”

이건 전부 책임이 불분명합니다.

AI는: • 판단은 했는데 • 말하지 않고 • 그냥 진행해버립니다

⸻

5️⃣ AI가 ADR을 감지하는 “실제 신호들”

AI는 보통 아래 순간에 ADR이 필요하다는 걸 내부적으로 이미 알고 있습니다. • “There are a few options…” • “One approach is…, another approach is…” • “This trade-off means…” • “To avoid future issues…”

👉 이 문장들이 나오면 이미 결정 구간에 진입한 겁니다.

그래서 규칙은 이거예요:

옵션을 나열하기 시작하면 → ADR 후보

⸻

6️⃣ 한 단계 더: “ADR 후보”라는 말을 쓰게 만들기

조금 더 공격적으로 가고 싶으면:

If a decision meets the ADR criteria, label it explicitly as: “ADR candidate” and stop implementation until acknowledged.

AI는 이렇게 말하게 됩니다:

“This is an ADR candidate. Should I proceed with drafting the ADR?”

이게 되면: • ADR 누락 거의 0 • 사람은 “예/아니오”만 하면 됨

⸻

7️⃣ ADR을 AI가 대신 써도 되는 경계

이건 중요합니다.

AI가 ADR을 써도 되는 경우 ✅ • 사람이 “이 결정은 맞다”고 확인한 후 • 또는 사람이 “ADR 초안 써줘”라고 명시했을 때

AI가 하면 안 되는 경우 ❌ • 결정을 대신 내려버리는 것 • 합의 없이 ADR을 확정하는 것

AI는 기록자이지, 결정권자가 아니다

⸻

8️⃣ 실전용 초단축 규칙 (에이전트 머릿속용)

이걸 AI에게 먹이면 정말 잘 작동합니다:

If you have to explain why, not just how, stop and request an ADR.

⸻

한 문장으로 요약 • AI에게 ADR을 쓰게 하지 말고 • AI에게 ADR이 필요하다고 말하게 하라 • 말하는 순간, 사람에게 공이 넘어온다

이 구조가 잡히면: • ADR 누락 ↓ • AGENTS.md 비대화 ↓ • “이거 왜 이렇게 됐지?” ↓ • AI의 자율성은 유지되면서 사고는 통제됨

스킬 작성과 포스트 작성에 gpt의 도움을 받았습니다. GPT-5.2 물 올랐네요.

Join the Investigation

Get the latest updates on my projects and indie hacking journey directly in your inbox.

No spam. Unsubscribe anytime.