LLM Hallucination 방지를 위한 AGENTS.md 기반 API 명세 구조 설계

I Shipped an npm Package With an AGENTS.md File — Here's Why Every Library Should Do This

jeetvora3312026년 5월 10일3분beginner

AI 요약

Context

전통적인 README.md가 마케팅 문구와 시각적 요소 중심의 인간 지향적 구조로 작성됨에 따라, LLM 기반 코딩 에이전트가 정확한 API 명세와 Prop 조합을 파악하지 못하는 한계 발생. 이로 인해 에이전트의 환각 현상으로 인한 잘못된 코드 생성과 이에 따른 사용자 버그 리포트 증가라는 문제 직면.

Technical Solution

AI 에이전트 전용 Reference Manual인 AGENTS.md 파일을 패키지 루트에 별도 설계
package.json의 files 배열에 AGENTS.md를 명시하여 npm tarball에 포함함으로써 에이전트가 node_modules 내에서 로컬로 즉시 참조하는 구조 구현
단순 API 목록을 넘어 Full export list, Type definitions, Numbered patterns를 포함한 엄격한 명세 체계 수립
Decision tree 설계를 통해 상황별 최적의 패턴 선택 기준을 명시하여 에이전트의 판단 로직 최적화
'Wrong vs Correct' 대조 기반의 Anti-pattern 섹션을 구성하여 LLM의 컨텍스트에 오류 방지 지식을 사전 주입

실천 포인트

1. package.json의 files 필드에 AGENTS.md 포함 여부 확인

2. 모든 Public Symbol에 대한 엄격한 타입 정의 및 기본값 명시

3. LLM이 자주 실수하는 패턴을 ❌/✅ 형식으로 정의한 Anti-pattern 가이드 작성

4. 복잡한 API 조합 시 결정 트리(Decision Tree) 구조의 가이드라인 제공

태그

#npm #LLM #API Design #Hallucination #Developer Experience

원문 읽기