adr-index-skill

ENGLISH 한국어

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

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

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

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

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

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

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

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

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

  1. 컨텍스트 비용 증가
  1. 잡음 증가
  1. 유지보수 부담

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

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

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

하는 것입니다.

ADR에 남기면 좋은 것

ADR에 굳이 안 남겨도 되는 것

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

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

1) ADR 상단 메타만 스캔

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

이유:

2) 헤더 형식 검증

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

예:

이 포맷을 쓰면:

3) 메타데이터 파싱

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

4) 비-ADR 파일은 제외

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

5) 인덱스 생성

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

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

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

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

권장 타이밍

실행 명령

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

핵심 규칙은 간단합니다.

예를 들어,

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

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

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

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

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

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

레포:

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:

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.