agent.md로 LLM 생성 코드의 품질 높이기

2025년에는 컴파일조차 못 하던 LLM이 2026년에는 복잡한 구현과 버그 분석까지 해냈지만, 스파게티 코드와 부족한 주석·구조 탓에 프로덕션에 바로 쓰기 어려웠음 세션마다 반복하던 코드 리뷰 지침을 agent.md에 모아 프롬프트에 자동 주입하자, 생성 코드가 직접 작성한 수준에 가까워지고 검토 초점도 스타일에서 아키텍처와 설계로 이동함 짧고 정확한 문장, 매직 넘버 제거, 이른 반환, enum 매개변수, 접근 제한 유지, 계층 경계 준수와 관련 없는 변경 최소화 등을 규칙으로 지정함 버그 수정은 실패하는 테스트 작성부터 시작하고, 커밋 메시지는 50자 이내 제목·명령형 사용·본문 72자 줄바꿈 등 7개 규칙을 따르게 함 긴 문맥에서는 중간 지침을 덜 따르는 문맥 희석이 발생하므로 기능마다 새 세션을 시작하거나 Reload agent.md로 지침을 다시 불러와야 하며, 생성 코드는 여전히 직접 검증해야 함 반복적인 코드 리뷰를 agent.md로 자동화 2025년 중반 Rust 기반 mDNS 구현체 libadbmdns 개발에 처음 LLM을 사용했지만, 생성된 코드는 컴파일되지 않았음 2026년 1월 다시 시도하자 복잡한 indexed-binary heap 클래스를 작성하고, Windows IOCP 구현 때문에 발생한 polling 크레이트의 드문 버그도 찾아냄 기능 구현 능력과 달리 결과물은 주석과 구조가 없는 스파게티 코드였으며, 프로덕션 수준으로 정리하는 시간이 개발 속도 향상을 상쇄했음 2026년 3월 Antigravity와 VS Code의 Claude Code 플러그인 같은 에이전트 IDE에서 staged 코드를 반복 검토함 매직 넘버를 사용하지 않음 코드의 의도를 설명하는 짧은 주석을 추가함 함수 이름을 짧게 만듦 반복 지시를 거치면 품질이 직접 작성한 코드에 가까워졌지만, 새 세션마다 같은 내용을 되풀이해야 했음 코딩 하네스는 세션 시작 시 agent.md를 읽어 프롬프트에 주입하므로, 반복되는 코딩 스타일 지침을 저장하기 적합함 프로젝트 루트에 개인용 agent.md를 두면 됨 gemini.md나 claude.md를 agent.md로 심볼릭 링크하면 여러 환경에서 적용할 수 있음 새 규칙이 필요하면 편집기를 직접 열지 않고 에이전트에게 agent.md 업데이트를 요청할 수도 있음 agent.md에 담은 코드 작성 규칙 사람이 읽는 주석·커밋 메시지·응답은 단어를 신중히 골라 최대한 짧고 직접적으로...