LLM 생성 코드 품질을 높이는 나만의 agent.md
My agent.md to improve LLM-assisted code quality
Fabien Sanglard는 2025년 중반 LLM 코딩에 처음 도전했지만 실망했습니다. 2026년 1월에 다시 시도했고, 이번에는 복잡한 인덱스 바이너리 힙 클래스를 작성하고 Windows IOCP 관련 난해한 버그를 찾아내는 등 성능이 크게 개선되었지만, 코드 품질은 형편없었습니다. 이후 에이전트 IDE(예: Antigravity, VS Code의 Claude Code)를 사용하며 반복적인 지시를 주는 데 지쳐, 프로젝트 루트에 두는 설정 파일인 agent.md에 코딩 스타일 규칙을 정리했습니다. 이 글에서는 규칙 목록과 함께, 컨텍스트 희석 문제를 완화하는 방법(새 세션 시작, 'Reload agent.md' 명령)과 에이전트가 스스로 agent.md를 업데이트하도록 하는 팁을 공유합니다.
LLM은 끊임없이 환각을 일으키며 신뢰할 수 없습니다. 여전히 많은 검증과 반복이 필요하지만, 이제는 코드 스타일 대신 아키텍처와 설계에 집중할 수 있습니다.
HN 토론
171- OptionOfT
이 중 상당수는 린팅으로 강제해야 합니다. 그래야 여전히 코드를 직접 작성하는 사람들도 같은 종류의 피드백을 받을 수 있습니다. 예를 들어, 한 줄짜리 if 문에도 항상 {}를 사용하라, 함수 이름을 짧게 유지하라(30자 미만) 같은 것들입니다.
그리고 다음은 정말 많은 변경을 유발하는 패턴입니다:
- 블록이 무엇을 하는지, 왜 하는지 설명하는 작고 핵심적인 주석을 추가하세요. 가능하면 예시를 사용하세요. 전체 시스템을 설명하기 위해 ASCII 그림을 제안하세요.
무엇이 코드인지가 중요합니다.
- imjonse
"사람이 읽을 내용(주석, 커밋 메시지, 프롬프트에 대한 답변)을 작성할 때는 가능한 한 적은 단어를 사용하세요. 각 단어를 세심하게 선택하여 분량을 최소한으로 줄이세요. 간결하게, 요점만 전달하세요. 적을수록 좋습니다."
이 첫 문단이 간결함에 대한 같은 메시지를 전달하기 위해 많은 단어와 다양한 방식을 사용하는 아이러니가 있습니다. 하지만 이 파일은 사람이 읽기 위한 것이 아니므로 다른 규칙이 (여전히?) 적용되어야 합니다.
저는 프롬프트에서 이렇게 하는 자신을 발견합니다. 아마도 우리가 강조하고 싶은 맥락의 일부에 더 많은 가중치를 두는 방법이고, LLM이 한 번만 언급된 메시지를 이해하지 못할 것이라는 신뢰 부족을 보여주는 것 같습니다.
- andai
> - 함수 이름을 짧게 유지하세요. 30자 미만.
최근에 GPT에게 브라우저 게임을 Rust로 포팅해 달라고 요청했습니다. GPT가 이 보석 같은 이름을 자발적으로 제안했습니다:
draw_image_with_html_image_element_and_sw_and_sh_and_dx_and_dy_and_dw_and_dh(...)
저는 GPT가 뭔가 좋은 것을 하고 있다고 생각했지만, 알고 보니 그것이 실제 함수 이름이었습니다!
https://docs.rs/web-sys/latest/web_sys/struct.CanvasRenderin...
- YuechenLi
우리 모두 AGENTS.md를 공유하고 있으니 저도 제 것을 공유하고 싶습니다. 대부분의 경우 LLM이 좋은 코드를 작성하는 데 필요한 것은 이것뿐이고, 나머지는 프로젝트별로 추가할 수 있기 때문입니다:
----
*수렴 규칙*
모든 실질적인 작업은 정확히 세 가지 상태 중 하나로 끝나야 합니다:
A. 성공
의도한 기능이 실제 경로에서 작동하고 실제 동기 부여 사례가 실질적으로 개선됩니다.
B. 의미 있는 진행
기능이 완전하지는 않지만, 진짜 차단 요소 하나가 제거되고 다음 차단 요소가 증거와 함께 분리됩니다.
C. 정직한 중단
추가 작업은 지나치게 광범위한 범위 확장, 과도한 기술 부채, 취약한 패치, 또는 얽힌 로직을 요구할 것입니다. 중단하고 구체적인 증거와 함께 이유를 보고하세요.
작업이 수렴을 멈추면 패치를 계속 생성하지 마세요.
활동을 진행과 혼동하지 마세요. 실패한 시도는 더 좁은 문제, 더 강력한 증거, 또는 정당한 중단을 남길 때만 허용됩니다.
부분 작업은 코드베이스를 이전보다 더 깨끗하고, 더 읽기 쉽고, 더 진단 가능한 상태로 남겨야 합니다.
----
기사의 AGENTS.md 중 상당수는 LLM 에이전트에게 이미 알고 있는 내용(예를 들어, 대부분의 경우 화살표 안티패턴 대신 완전한 switch/match 문을 사용해야 한다는 것을 알고 있음)을 말하거나, 적극적으로 해로워 보입니다("함수 이름을 짧게 유지"는 임의적이며 LLM이 읽고 리뷰하기 더 어려운 이상한 약어를 만들 수 있습니다).
- gregwebs
훌륭한 내용입니다. 하지만 대부분은 AGENTS.md에 넣을 곳이 아닙니다. 이 기사에 나온 대부분의 내용은 CODING_STANDARDS.md에 넣을 수 있습니다. 제가 사용하는 스킬은 코드를 읽고 리뷰할 때 이 문서를 찾아서 코드를 읽는 동안 컨텍스트를 오염시키지 않습니다.
또한 (계획 단계와 생성된 코드 모두에 대한) 하위 에이전트 리뷰가 있어서 이러한 문제 중 일부를 잡아내고 수정을 요구할 수 있습니다. [1]
> - 프롬프트가 버그 수정을 나타내는 경우, 수정을 바로 작성하지 마세요. 먼저 테스트를 작성하세요. 테스트가 실패하는 것을 확인하세요. 그런 다음 수정을 작성하세요. 그리고 테스트가 통과하는 것을 확인하세요.
저는 항상 /tdd [2]를 사용합니다. 가끔 어리석은 테스트가 나오기도 하지만, 결함이 훨씬 적은 코드를 생성합니다. 버그에만 해당되는 것이 아닙니다.
[1] https://github.com/gregwebs/skills-sdlc/
[2] https://github.com/mattpocock/skills/blob/main/skills/engine...
- Supermancho
이런 것들을 읽는 것은 흥미롭습니다.
저는 이것을 13개의 코드 작성 규칙(최소 16개로 해석됨 - 코드 들여쓰기 줄이기로 시작)과 커밋 메시지 지침 세트로 설명하겠습니다. 커밋 메시지 지침은 스타일 특정적이고 저에게 흥미롭지 않기 때문에 무시하기로 선택했습니다.
이 규칙 중 8~9개는 필요하지 않습니다. 기본적인 컴퓨터 과학은 제가 사용하는 에이전트에게 요청할 필요가 없었습니다. 예를 들어 명시적 인터페이스가 필요하다는 것을 설명하는 것은 필요한 지침이 아니며, 조기 반환을 활용하는 것도 마찬가지입니다.
불분명한 지침은 제한적인 효용이 있습니다. "코드를 읽는 사람이 숨 쉴 수 있게 하라" 또는 "코드 들여쓰기를 줄여라"가 무엇을 의미하는지는 주관적이며 효과적이지 않을 것입니다. 아마도 사용 중인 언어에 대한 훈련에 공백이 있을 수 있으며, 다른 사람들은 그렇지 않을 수도 있습니다. 측정하려면 규칙을 적용할 때 문자열을 출력하도록 요청하세요. 무엇이 효과가 있고, 무엇이 효과가 없으며, 얼마나 자주 효과가 있는지 빠르게 알 수 있습니다.
여기에는 3~4개의 스타일 선택이 포함되어 있습니다.
나머지는 제가 사용하지 않을 것이지만, 우리 모두 다른 것들로 인해 피해를 입으므로 이해합니다.
- getnormality
이것은 대부분 사람들이 스스로 해결해야 하는 문제입니다. 예를 들어, 저는 거의 1년 동안 Claude와 작업해 왔지만 "화살표 안티패턴" 코드를 작성하는 것을 한 번도 본 적이 없습니다. 그것과 나머지 많은 것들은 제 프로젝트에서 잡음이 될 것입니다. 에이전트 지침은 프로젝트별 경험을 통해 배우는 것이 가장 좋습니다.
- oumua_don17
AGENTS.md의 이 한 줄만으로도 장황함과 과장을 줄이거나 없애는 데 더 나은 결과를 얻었습니다.
**항상 ASD-STE100 Simplified Technical English를 사용하세요.
면책 조항: 이 내용을 다른 HN 게시물에서 보았지만 지금은 찾을 수 없습니다.