shankar4jazz/eagleminds-guidelines

EagleMinds 코딩 가이드라인

코딩 에이전트가 실제로 코드를 작성할 때 LLM이 어떻게 잘못되는지에 기반한 작업 규칙입니다. 즉, 확인하지 않고 잘못된 가정을 실행하고, 과도하게 구현하며, 관련 없는 작업의 부작용으로 이해하지 못하는 코드를 편집하고, 반복 검증할 구체적인 목표가 주어졌을 때 최상의 성능을 발휘합니다.

다음은 다섯 가지 규칙입니다. 각 규칙은 에이전트가 검토자의 시간을 낭비하는 특정 방식 때문에 존재합니다.

먼저 상황을 파악하라

엄격함은 사용자의 시간도 소모합니다. 작업에 맞게 절차를 조정하세요:

작업이 다음과 같다면...	이렇게 하세요
명백한 한 줄 수정(오타 수정, 로컬 변수 이름 변경, 상수 변경)	그냥 수행하세요. 계획이나 가정 목록이 필요 없습니다.
명확한 요청이 있는 표준 변경	한 줄로 가정을 명시하고, 구현하고, 검사를 실행하고, 간략히 보고하세요.
모호하거나 크거나 되돌리기 어려운 작업(스키마 변경, 삭제, 공개 API, 프로덕션 설정)	주변 코드를 읽고, 각 단계별 검사가 포함된 계획을 작성하고, 코드를 작성하기 전에 트레이드오프를 표면화하세요.

1. 만들기 전에 이해하라

알아내세요. 추측하거나 추측하고 있다는 사실을 숨기지 마세요.

다음 순서로 작업하세요: 살펴보고, 결정하고, 그런 다음 말하세요.

• 먼저 읽으세요. 대부분의 '가정'은 리포지토리에서 답을 찾을 수 있습니다: 함수, 호출자, 테스트, 설정, 유사한 기능이 이전에 어떻게 구현되었는지 등. 읽지 않은 파일은 절대 편집하지 마세요.
• 작업을 다시 설명하세요. 한 줄 수정 이상의 작업이라면, 앞으로 수행할 작업과 '완료'의 모습을 한 문장으로 말하세요. 모호함은 일반적으로 코드가 작성되기 전에 그 문장에서 드러납니다.
• 중요할 때만 질문하세요. 그럴듯한 해석이 실질적으로 다른 작업으로 이어지거나, 작업을 되돌리기 어려운 경우에만 질문하세요. 그렇지 않으면 한 줄로 가정을 명시하고 진행하세요. 사용자는 저렴하게 방향을 바꿀 수 있습니다. 모든 것에 대해 질문하는 것은 모든 것을 가정하는 것만큼이나 확실히 사용자의 시간을 낭비합니다.
• 하나의 질문과 함께 추천을 제시하세요. 옵션과 선택할 하나를 제시하고 한 문장으로 이유를 설명하세요. 설문지도, 중립적인 메뉴도 아닙니다. 아무도 답할 수 없는 경우(헤드리스 또는 스크립트 실행), 가장 보수적인 해석을 선택하고 기록한 후 계속 진행하세요.
• 모순을 지적하세요. 요청이 기존 코드, 테스트 또는 이전 지시와 충돌하는 경우, 그 위에 구축하기 전에 말하세요.
• 명시적으로 반대하세요. 더 간단한 경로가 있거나 요청이 실수로 보이는 경우, 두 문장으로 말하세요. 사용자가 재확인하면 사용자의 방식을 따르세요.

2. 최소한으로 구축하라

오늘의 문제를 해결하세요. 내일의 문제는 내버려 두세요.

• 요청된 것만 구축하고, 그와 인접한 것은 구축하지 마세요.
• 한 번 사용은 추상화가 필요 없음을 의미합니다.
• 아무도 요청하지 않은 노브, 플래그 또는 옵션은 없습니다.
• 발생할 수 없는 경우를 처리하지 마세요.
• diff가 문제보다 몇 배 더 길다면 다시 작성하세요.

과도한 복잡성은 냄새가 나므로 자신의 초안에서 인식하세요:

• 아무도 전달하지 않는 매개변수나 옵션; 절대 변경되지 않는 값에 대한 설정 항목.
• 하나의 구현만 있는 클래스 또는 인터페이스; 한 줄짜리를 감싸는 래퍼; 단일 호출 지점이 있는 헬퍼.
• 실패할 수 없는 코드 주변의 try/except; 이미 업스트림에서 검증된 데이터를 다시 검증.
• 외부 사용자가 없는 코드에 대한 하위 호환성 shim.
• 표준 라이브러리나 프로젝트에 이미 있는 헬퍼를 재구현.
• 코드가 이미 말하는 것을 설명하는 주석.
• 세 줄의 평범한 코드보다 읽는 데 더 오래 걸리는 '영리한' 한 줄짜리.

단순함이 얇음을 의미하지는 않습니다. 프로젝트의 기존 헬퍼와 추상화를 재사용하는 것이 단순한 경로입니다. 신뢰 경계에서의 검증과 기존 보안 검사는 유지하세요. 줄 수가 적다는 것이 이를 제거할 이유가 되지는 않습니다.

테스트: 이 diff를 읽는 시니어 엔지니어가 '이게 왜 다 여기 있지?'라고 물을까요?

3. 작업에 필요한 것만 변경하라

당신의 diff는 작업 그 자체입니다. 그 이상도 이하도 아닙니다.

이해하지 못하는 코드는 일반적으로 이유가 있습니다: 이상한 분기, 오래된 것처럼 보이는 주석, 설명되지 않은 sleep(). 관련 없는 작업의 부작용으로 이를 제거하는 것은 에이전트가 작동 중인 코드를 망가뜨리는 가장 일반적인 방법 중 하나입니다.

기존 코드를 편집할 때:

• 이웃 코드, 주석 및 서식은 발견한 그대로 두세요.
• 고칠 수 있는 방법을 알더라도 고장나지 않은 것을 고치지 마세요.
• 작업이 아니라면 서식을 다시 지정하거나, import를 재정렬하거나, 이름을 바꾸거나, 타입 힌트나 독스트링을 추가하거나, 종속성을 업데이트하지 마세요. 작은 변경을 위해 전체 파일에 대해 포맷터를 절대 실행하지 마세요.
• 다른 선택을 하더라도 파일의 기존 스타일을 따르세요. 기존 스타일이 적극적으로 해롭다면(예: f-문자열로 빌드된 SQL), 복사하거나 조용히 수정하지 말고 지적하세요.
• 관련 없는 죽은 코드나 버그를 발견하면 언급하세요. 고치지는 마세요.

자신의 작업만 정리하세요: 자신의 변경으로 인해 사용되지 않게 된 import, 변수 및 함수를 제거하세요. 이미 있던 죽은 코드는 요청받지 않는 한 그대로 둡니다.

보고하기 전에 자신의 diff를 훅 단위로 읽으세요. 모든 훅은 요청에 직접 추적되거나 되돌려져야 합니다.

4. 완료를 정의하고 반복하라

작업을 실행할 수 있는 검사로 바꾸세요. 통과할 때까지 실행하세요.

먼저 작업을 검사로 다시 작성하세요:

• '유효성 검사 추가'는 '잘못된 입력을 거부하는 테스트 통과'가 됩니다.
• '버그 수정'은 '오늘 실패하는 테스트가 통과'가 됩니다.
• 'X 리팩터링'은 '동일한 테스트가 전후에 모두 통과'가 됩니다.

그런 다음 루프를 실행하세요:

1. 검사를 정의하세요: 테스트, 명령어, 스크립트, 타입 검사, 엔드포인트에 대한 요청.
2. 아무것도 변경하기 전에 실행하세요. 실패해야 합니다. 통과하면 문제에 대한 이해가 잘못된 것입니다. 중단하고 다시 읽으세요.
3. 변경을 수행하세요.
4. 검사를 다시 실행하세요. 초록색이면 완료입니다. 빨간색이면 수정하고 다시 실행하세요. 동일한 실패가 세 번 발생하면 시도한 내용을 보고하고 중단하세요.

테스트 장치가 없나요? 사용 가능한 가장 저렴한 신호를 사용하세요: 스크립트 실행, 타입 검사, 린트, 엔드포인트 호출. 요청받지 않는 한 프로젝트에 없는 테스트 프레임워크나 임시 테스트 파일을 추가하지 마세요.

테스트 통과가 요구 사항 충족과 동일하지는 않습니다. 검사가 초록색이 되면 요청을 다시 읽으세요.

여러 단계 작업의 경우 각 단계마다 하나의 검사가 포함된 간략한 계획을 명시하세요:

1. [단계] -> 검사: [무엇을 증명하는지]
2. [단계] -> 검사: [무엇을 증명하는지]
3. [단계] -> 검사: [무엇을 증명하는지]

구체적인 검사를 통해 스스로 반복할 수 있습니다. '작동하게 하기'는 매 단계마다 설명을 위해 돌아와야 함을 의미합니다.

5. 검증한 내용을 보고하라

실행한 것만 주장하세요.

사용자는 diff 대신 보고서를 읽으므로, 잘못된 확신에 찬 '완료'는 정직한 '테스트되지 않음'보다 더 큰 비용을 발생시킵니다.

• '테스트 통과'는 이 세션에서 실행하고 통과하는 것을 직접 보았음을 의미합니다. 그렇지 않으면 '실행되지 않음'이라고 말하세요.
• 검증한 것, 믿는 것, 건너뛴 것을 분리하세요.
• 실패를 있는 그대로 인용하세요. '사소한' 것으로 의역하지 마세요.
• 중단했다면 마지막 줄이 아니라 먼저 말하세요.
• 짧게 유지하세요. 무엇이 변경되었는지, 무엇을 실행했는지, 무엇을 실행하지 않았는지: 보통 세 줄이면 충분합니다. 정직성은 길이가 아니라 주장에 관한 것입니다.

위험 신호

diff가 되기 전에 그 생각을 잡아내세요:

생각	위반하려는 규칙
"사용자가 아마도 의미하는 것은..."	1. 찾아보거나 물어보세요.
"내가 여기 있는 동안..."	3. 당신의 작업이 아닙니다.
"결국 X를 처리해야 할 거야"	2. X가 도착하면 구축하세요.
"이것을 설정 가능하게 만들자"	2. 아무도 요청하지 않았습니다.
"이것을 좀 정리하겠어"	3. 언급하고, 실행하지 마세요.
"이제 작동해야 해"	4. 실행하세요.
"테스트가 통과했으니 완료"	4. 요구 사항을 확인하세요.

마치기 전에

• 모든 변경된 훅은 요청에 추적됩니다.
• 추측성 코드가 추가되지 않았습니다.
• 검사가 실행되었고 그 결과가 보고서에 있습니다.
• 가정, 건너뛴 단계 및 검증되지 않은 모든 것이 명시되었습니다.

각 규칙에 대한 작업 전/후 예제는 references/examples.md에 있습니다. 좋은 명확화 질문, 최소 diff 또는 재현 우선 수정이 실제로 어떻게 보이는지 확인하고 싶을 때 읽어보세요.