구현 수칙

이 규칙은 "누가"가 아니라 "무엇을 하는가"에 붙는다. 구현을 맡은 쪽이 사람이든
실행자 에이전트든 관리자 자신이든 동일하게 적용된다. 워크플로우에 따라 구현자가
바뀌어도 규칙은 그대로다.

받는 쪽은 정해진 것을 정확히 구현하는 역할이다. 지시서에 없는 것을 채워 넣는 역할이 아니다.

1. 결정하지 않는다 — 이게 첫 번째다

아키텍처·데이터셋·모델·라이브러리 선택, 범위 확대·축소, 일정·우선순위는 구현자의 몫이 아니다.

막히면 그럴듯한 선택을 만들어내기 쉽다. 근거처럼 보이는 설명까지 붙여서. 그래서 명시한다.

다음에 해당하면 진행하지 말고 보고한다:
- 두 가지 이상의 방식 중 무엇을 택할지 정해야 할 때
- 지시서에 없는 범위로 넓혀야 할 때
- 데이터셋·모델·라이브러리를 새로 고르거나 바꿔야 할 때
- 되돌릴 수 없는 작업이 필요할 때
- 지시서의 배경 설명이 실제와 다를 때

이건 실패가 아니라 정상적인 보고다. 추측해서 진행하는 것이 실패다.

특히 마지막 항목 — 지시서의 배경이 틀릴 수 있다. 직접 확인하고, 다르면 보고한다.
지시서를 그대로 믿고 진행하면 잘못된 전제 위에 작업이 쌓인다.

위 트리거 문구는 [[task-brief]] §6에도 있다 — 지시서를 쓰는 쪽이 그것을 지시서에 박아 넣는다.
한쪽을 고치면 다른 쪽도 함께 고친다. 두 곳에 있는 같은 규칙은 언젠가 어긋난다.

2. 원본을 보존한다

원본 코드를 직접 고치지 않는다. 신규 파일로 작성한다. 참조는 하되 원본은 남긴다.

되돌릴 수 있어야 하고, "고치기 전에 어땠는지"를 나중에 볼 수 있어야 한다.

⚠️ 복사본을 만들어 거기서 고치는 것도 위반이다. "이 파일 고치지 마"를 글자 그대로만
받아들이면 사본을 떠서 고치게 되는데, 그러면 어느 것이 진짜인지 알 수 없어진다.
금지의 취지는 파일 하나를 지키는 것이 아니라 원본과 대조 가능한 상태를 지키는 것이다.

원본을 꼭 고쳐야 한다면 그것 자체가 §1의 보고 대상이다.

3. 핵심부에 주석을 단다 — 코드리뷰를 대신한다

무엇을·왜·어떤 근거로(지시서 어느 항목, 논문·문서 어느 부분) 그렇게 했는지 적는다.

구현자는 지시서를 읽었지만 나중에 읽는 사람은 안 읽었다. 근거가 코드에 없으면
나중에 그 줄을 고쳐도 되는지 아무도 판단할 수 없다.

4. 중간에 끊겨도 이어서 갈 수 있게 만든다 — 단계별 개별 실행

학습·검증·예측처럼 오래 걸리고 독립적으로 실패하는 단계는 따로 돌릴 수 있어야 한다.
한 번에 다 돌리는 스크립트만 있으면, 마지막 단계에서 끊겼을 때 처음부터 다시 해야 한다.

# 대상 1개 × 단계 1개 단위로 실행 가능하게
python <스크립트> --model <모델명> --stage train     # 또는 eval / predict
python <스크립트> --model <모델명> --stage eval

• 일괄 스크립트는 개별 스텝을 순차 호출하는 wrapper로만 둔다.
• 산출물 파일명에 실행을 가르는 인자를 전부 넣는다 — 서로 덮어쓰지 않게.
  위 예시라면 results/<모델명>_<단계>.json. 데이터셋·조건이 더 붙으면 그것도 이름에 넣는다.
• 이미 끝난 것은 스킵할 수 있게 한다(--force 로 재실행). 중간에 끊겨도 이어서 간다.

4-1. 명령을 부른 것과 성공한 것은 다르다

결과를 확인하기 전에는 세지 않는다.

실제 사고: 설치 스크립트가 링크 생성 명령을 부른 뒤 확인 없이 카운터를 올렸다.
명령 5개가 실패했는데 화면에는 오류가 지나가고 요약은 "26개 생성, 0개 실패" 였다.
그 자리에는 낡은 사본이 그대로 남아 두 버전이 공존하게 됐다.

• 만들었으면 만들어졌는지 확인하고 센다. 지웠으면 없어졌는지 확인한다.
• 실패는 모아서 마지막에 경로와 함께 출력하고, 0이 아니면 종료 코드도 0이 아니게 한다.
  요약 줄만 보고 넘어가는 일이 실제로 생긴다.
• 오류 메시지가 스크롤을 지나갔다고 처리된 것이 아니다. 집계에 반영되지 않은 오류는
  없는 것과 같다.

이건 부르는 쪽이 지킬 규칙이다. 받은 결과를 검증하는 쪽 규칙은 [[work-review]] 에 있다.

5. 로그는 프로젝트 폴더에 남긴다

PYTHONIOENCODING=utf-8 python <스크립트> ... 2>&1 | tee <프로젝트>/results/logs/run.log

• 임시 폴더(scratchpad/tmp)에 남기지 않는다. 세션이 끝나면 사라져 실행 근거가 없어진다.
• 백그라운드 실행도 로그 경로를 프로젝트 폴더로 직접 지정한다.
• ⚠️ 콘솔 기본 인코딩이 UTF-8이 아닌 환경에서는 로그가 깨진다. PYTHONIOENCODING=utf-8.
  깨진 로그로는 원인 추적이 사실상 불가능하다.

6. 라이브러리는 공식 문서를 먼저 확인한다

SDK·프레임워크·API를 쓸 때 기억에 의존하지 않는다. 버전에 따라 시그니처가 바뀐다.
문서 조회 수단이 있으면 그것을 쓰고, 없으면 설치된 버전의 도움말·소스를 직접 확인한다.

7. 되돌릴 수 없는 작업은 하지 않는다

삭제·배포·외부 전송은 구현자가 스스로 실행하지 않는다. 필요하면 건의한다.
샌드박스로 막혀 있다면 우회하지 않는다 — 막혀 있다는 사실 자체가 지시다.

8. 문서 경계 — 코드 레벨만 쓴다

쓴다	쓰지 않는다
코드 주석, 코드 README	전략·계획 문서
작업내역 로그, 완료 보고서	진행상황·결정사항 문서

전략 문서는 관리자가 완료 기록을 근거로 정제해 갱신한다. 구현자가 직접 고치면
같은 내용이 두 곳에서 서로 다르게 자란다.

9. 작업 하나가 끝날 때마다 기록한다

콘솔 로그와 별개로, 사람이 읽을 기록을 남긴다. 구두 보고로 끝내지 않는다 —
관리자는 이 기록을 근거로 상위 문서를 갱신한다.

프로젝트 루트의 작업내역 문서에 날짜순으로 append한다. 기존 항목은 고치거나 지우지 않는다.
프로젝트마다 이름이 다르므로 있는 것을 먼저 찾고, 없으면 만들되 어디에 만들었는지 알린다.

## YYYY-MM-DD — <작업 제목>
- 지시 출처: <지시서·계획문서 절 번호, 또는 대화 요약>
- 수행 내용: <무엇을 구현·실행했는지, 핵심 설계 포인트>
- 결과: <수치·산출물 경로>
- 소요 시간: <실측치>
- 로그: `results/logs/<파일명>`
- 확인 필요·이슈: <있으면 명시, 없으면 "없음">

정직하게 적는다. 실패·부분완료·미해결 이슈를 숨기지 않는다. 관리자가 다음 지시서를
만들 때 이걸 근거로 쓰므로, 숨기면 다음 지시가 틀린 전제 위에 만들어진다.

상세 보고서를 따로 요구하는 워크플로우라면 그 형식을 함께 따른다 — 작업내역은
한 줄 요약과 경로, 상세는 보고서 쪽이다.

연계

• 이 규칙을 전제로 지시서를 쓴다 — [[task-brief]]
• 결과를 검증하는 쪽은 [[work-review]]
• 프로젝트에 더 구체적인 실행 규약(재현 절차 등)이 있으면 그쪽이 우선하고,
  이 수칙은 그 아래에서 함께 지킨다.

이력 (필수 기록)

• 생성일: 2026-08-27
• 업데이트 횟수: 2
• 최근 업데이트: 2026-08-27
• 사용 이력:
  • 2026-08-27 — §4-1(명령을 부른 것 ≠ 성공한 것) 추가. 이 저장소의 설치 스크립트가
    링크 생성 결과를 확인하지 않고 카운터를 올려, 5개가 실패했는데 "26개 생성,
    0개 실패"로 보고한 사고에서 나왔다. 낡은 사본이 남아 두 버전이 공존하게 됐다.
    부르는 쪽의 규칙이라 여기에 넣는다 — 받은 결과를 검증하는 쪽은 [[work-review]].
  • 2026-08-27 — 만든 직후 열어 읽어 결함 4건 수정. 검색 기반 검사(린터·식별정보·
    상호참조)는 전부 통과한 상태였다. 가장 심각한 것은 §2의 한 문장으로,
    "이유를 모르면 우회한다"가 정반대 지시로 읽히고 있었다 — 원 출처에서는
    지시서 쓰는 쪽에게 하는 현상 서술이었는데, 받는 쪽 규칙으로 옮기면서 명령문이 됐다.
    다른 스킬에서 문장을 가져올 때는 화자가 바뀐다는 점을 확인해야 한다.
    그 외: §4 제목이 §7("되돌릴 수 없는 작업")과 용어가 충돌해 개칭, 예시와 본문의
    인자 개수 불일치, 대상 문서가 없을 때의 처리 누락.
  • 2026-08-27 — 신설. 워크플로우에 실행자용 스킬이 완료 보고 하나뿐이고
    "어떻게 구현하는가"에 대한 수칙이 통째로 빠져 있는 것이 확인됐다.
    원인은 그 규칙이 프로젝트의 에이전트 지침 파일에 있었고, 스킬이 아니라서
    이관 검토 대상에 들지 않았기 때문이다 — 스킬만 훑으면 스킬 아닌 곳에 있는
    규칙은 보이지 않는다. 내용은 실제 운영에서 굳은 것이다.