My agent.md to improve LLM-assisted code quality

개요

LLM 기반 코드 생성 시 일관된 코드 품질을 유지하기 위해 agent.md 파일을 활용하여 LLM의 코딩 스타일과 규칙을 미세 조정하는 방법론을 제시합니다.

주요 내용

* LLM 코드 생성 초기 경험: 2025년 중반 LLM을 코딩에 처음 적용했을 때 컴파일되지 않는 코드가 생성되었으나, 2026년 1월 재시도 시에는 복잡한 클래스 생성 및 버그 탐지 능력을 확인했으나 코드 품질(스파게티 코드, 주석 및 구조 부재)이 낮아 실용성에 의문이 제기되었습니다.
* 에이전트 IDE 활용 및 반복적인 개선: 2026년 3월, Antigravity나 VS Code Claude Code 플러그인과 같은 에이전트 IDE를 사용하여 코드를 반복적으로 검토하고 "매직 넘버 사용 지양", "짧은 주석 추가", "짧은 함수 이름 사용" 등 지속적인 피드백을 통해 코드 품질을 크게 향상시켰으나, 매 세션마다 동일한 지시를 반복해야 하는 번거로움이 있었습니다.
* agent.md를 통한 해결책: 코딩 세션 시작 시 agent.md 파일을 로드하여 LLM 프롬프트에 주입함으로써 코딩 스타일 선호도를 미세 조정합니다. 반복되는 개선 사항을 agent.md에 추가하여 코드 품질을 일관되게 유지합니다.
* agent.md 예시 및 설정: FAB's AGENT.MD 예시는 간결한 표현, 구체적인 지시, 매직 넘버 및 문자열 상수화, 들여쓰기 감소, 짧은 함수 이름, 이넘(enum) 사용, 논리적 블록 간 공백 추가, 코드 블록 설명 주석, 멤버 가시성 제어, 추상화 수준별 프로그래밍, 레이어 경계 준수, 단일 라인 if문에도 중괄호 사용, 커밋 메시지 작성 규칙(50자 제목, 명령형 사용, 본문 설명 등)을 포함합니다. 버그 수정 시 테스트 먼저 작성 및 실패 확인 후 수정하는 프로세스를 권장합니다.
* "컨텍스트 희석(Context Dilution)" 문제 해결: LLM이 컨텍스트 중간의 지시를 덜 고려하는 "컨텍스트 희석" 현상을 완화하기 위해 컨텍스트를 짧게 유지(기능별 새 세션 시작)하고, agent.md를 명시적으로 다시 로드하도록 요청하는 방법을 사용합니다.
* agent.md 자동 업데이트: 편집기를 열지 않고 LLM에게 agent.md를 업데이트하도록 요청하여 새로운 규칙을 쉽게 추가할 수 있습니다.

시사점

agent.md 파일은 LLM이 생성하는 코드의 품질을 일관되고 높게 유지하는 효과적인 방법이며, 개발자가 반복적인 코드 스타일 개선 작업에 소모하는 시간을 줄여 생산성을 향상시킬 수 있습니다.