agent.md를 통한 LLM 지원 코드 품질 향상

agent.md 파일을 사용하면 개발자가 지속적인 스타일 선호도와 아키텍처 제약 조건을 LLM 프롬프트에 직접 주입할 수 있어, 인간의 역할을 기본적인 코드 스타일 수정에서 고수준 설계에 집중하는 것으로 전환할 수 있습니다. 이 접근 방식은 AI 지원 코딩 세션 중 발생하는 지루한 수동 피드백의 반복을 줄여줍니다.

agent.md 프레임워크

agent.md 파일은 프로젝트 루트의 설정 파일로, 에이전트형 IDE나 코딩 하네스가 LLM의 동작을 미세 조정하기 위해 자동으로 로드합니다. 매번 새로운 세션에서 동일한 스타일 수정을 반복하는 대신, 개발자는 이러한 요구 사항을 단일 진실 공급원(single source of truth)으로 코드화할 수 있습니다.

핵심 코딩 표준

프로덕션 수준의 코드 품질을 보장하기 위해 agent.md 파일에 다음 규칙을 권장합니다:

간결성: 주석, 커밋 메시지, 프롬프트 응답에서 가능한 한 적은 단어를 사용하십시오. 최상급 표현과 찬사를 피하십시오.
클린 코드 관행:
- "magic numbers"를 피하기 위해 반복되거나 의미 있는 값을 설명적인 상수나 enum으로 추출하십시오.
- "Arrow Anti-Pattern"을 피하기 위해 조기 반환(early returns)과 continue 문을 활용하여 들여쓰기를 줄이십시오.
- 가시성: 모든 필드와 함수를 기본적으로 private으로 유지하십시오. 접근 제어자를 internal 또는 public으로 변경하기 전에 명시적인 승인을 요청하십시오.
아키텍처 및 추상화:
- 저수준 메커니즘(예: raw hardware I/O, socket streams)을 전용 드라이버 레이어로 캡슐화하십시오.
- 각 레이어가 바로 아래의 인접한 레이어와만 통신하는 엄격한 계층형 경계 계층 구조를 준수하십시오.
문서화: 블록이 무엇을 하는지, 그리고 왜 하는지 설명하는 짧은 주석을 추가하십시오. 복잡한 시스템의 경우 예시나 ASCII 그림을 사용하십시오.
테스트: 버그를 수정할 때, LLM은 먼저 실패하는 테스트를 작성하고, 실패를 관찰한 후, 수정을 작성하고 통과 여부를 확인해야 합니다.

커밋 메시지 표준

깨끗한 Git 히스토리를 유지하기 위해 agent.md 파일은 커밋 메시지에 대해 7가지 규칙 시스템을 강제할 수 있습니다:

제목 줄과 본문을 빈 줄로 구분하십시오.
제목 줄을 50자 이내로 제한하십시오 (최대 72자).
제목 줄의 첫 글자를 대문자로 쓰십시오.
제목 줄 끝에 마침표를 찍지 마십시오.
명령조(imperative mood)를 사용하십시오 (예: "Fixed bug" 대신 "Fix bug").
본문 텍스트를 72자에서 수동으로 줄 바꿈하십시오.
본문을 사용하여 어떻게가 아닌 무엇을 그리고 왜를 설명하십시오.

컨텍스트 및 희석 문제 관리

컨텍스트 윈도우가 커짐에 따라, LLM은 프롬프트 중간에 위치한 지침에 주의를 덜 기울이는 "context dilution" (또는 "attention dilution") 현상을 겪습니다. 이 현상은 "Lost in the Middle" 연구 논문에서 기록되어 있습니다.

이를 완화하기 위해 개발자는 다음과 같이 해야 합니다:

세션 길이 제한: 컨텍스트를 짧게 유지하기 위해 각 개별 기능에 대해 새로운 세션을 시작하십시오.
강제 재로드: 코드 품질이 저하되기 시작하면 에이전트에게 명시적으로 "Reload agent.md"라고 명령하십시오.
자동 업데이트: 세션 중에 새로운 규칙이 발견되면 AI 에이전트 스스로에게 agent.md 파일을 업데이트하도록 요청하십시오.

커뮤니티 관점 및 비판

agent.md 방식이 일부에게는 효과적이지만, 구현에 관한 몇 가지 반론이 제나됩니다:

"A bunch of these should be enforce with linting... The what is the code."

비판론자들은 중괄호를 사용하는 한 줄 if 문이나 함수 이름 길이 제한과 같은 많은 규칙들이 프롬프트 지침보다는 자동화된 linter로 처리하는 것이 더 낫다고 주장합니다. 다른 개발자들은 너무 비대해진 agent.md 파일이 실제로 컨텍스트 소비를 증가시키고 성능을을 저하시킬 수 있다고 제안합니다.

커뮤니티의 추가 제안 사항은 다음과 같습니다:

관심사 분리: 코딩 표준을 CODING_STANDARDS.md 파일로 옮기고 agent.md for interaction preferences를 위해 유지하십시오.
Convergence Rules: 일부 개발자들은 AI가 끝없는, 취약한 패치를 생성하는 것을 방지하기 위해 모든 작업이 세 가지 상태 중 하나로 종료되어야 한다는 "Convergence rule"을 구현합니다: Success, Meaningful Progression, 또는 Honest Stop.
Simplified Technical English: AI의 장황함(verbosity)을 더 줄이기 위해 "ASD-STE100 Simplified Technical English"를 따르라는 지침을 사용하십시오.