Codex 작업 완료 보고서

Codex가 사용자에게 작업 완료를 알리기 전에, 검증 근거를 담은 한국어 보고서를 해당 프로젝트 폴더에 남긴다.
이 스킬은 실행자 전용이다. 관리자의 결과 기록([[result-record]])·외부 게시([[docs-append]])를
대체하지 않는다 — 이 보고서는 "내가 무엇을 했는가"를 남기는 원자료이고, 관리자는 그것을
정제해 기록하거나 밖으로 내보낸다.

구조화 JSON 보고와의 관계 (중요)

관리자가 codex-delegate 방식(codex exec --output-schema)으로 작업을 넘겼다면,
완료 보고는 2층으로 나간다. 둘 중 하나를 생략하지 않는다.

• JSON 완료보고 — 스키마가 강제하는 기계 검증용
  (summary/modified_files/commands_run/tests/unfinished/blocked).
  관리자의 검토는 이 필드들부터 본다. 여기서 누락하면 검토가 통과되지 않는다.
• 이 보고서(마크다운) — 사람이 읽는 상세 기록. 근거·수치·실행 방법·재현 절차.
  JSON이 담을 수 없는 맥락이 여기 들어간다.

작성한 보고서 경로(reports/YYYY-MM-DD_<작업명>/report.md)는 JSON의 modified_files
에도 반드시 포함한다. 두 산출물이 서로를 가리켜야 관리자가 대조할 수 있다.

미완·차단이 있으면 JSON의 unfinished/blocked 에 먼저 올린다. 마크다운에만 적고
JSON에 unfinished: [] 로 보내면 관리자는 완료로 읽는다 — 이것이 가장 흔한 사고다.

적용 단위

• 사용자에게 하나의 완료 결과로 보고할 수 있는 구현, 버그 수정, 테스트, 벤치마크, 논문 재현 단위에 적용한다.
• 모델×단계별 임시 실행이나 재시도마다 별도 보고서를 만들 필요는 없다. 이들은 같은 작업 보고서의 실행 내역으로 묶는다.
• 작업이 차단되었으면 완료라고 쓰지 않는다. 대신 같은 형식으로 상태 보고서를 작성하고 차단 근거와 남은 조치를 명시한다.
• 논문 Figure/Table 재현의 패널 작업은 프로젝트가 그런 전용 스킬을 두고 있다면 그쪽을 우선 적용한다. 그런 스킬은
  실행 방법과 간단한 코드 설명을 추가로 강제하며, 이 일반 완료 보고서 규칙도 충족한다.

저장 규칙

• 기본 경로: <프로젝트루트>/reports/YYYY-MM-DD_<작업명>/report.md
• 같은 작업을 갱신하면 기존 보고서를 덮어 숨기지 말고 보고서 안에 갱신 일시와 변경 내용을 누적한다.
• 로그는 복사하지 않고 프로젝트 내부의 영구 로그 경로(results/logs/ 등)를 링크한다.
• 이미지·JSON·체크포인트 등 산출물도 프로젝트 내부 상대경로와 실제 파일명을 기록한다.
• 프로젝트에 이미 확정된 보고서 폴더/명명 규칙이 있으면 그 규칙을 우선한다.

필수 내용

1. 작업 개요 — 목적, 범위, 완료/부분완료/차단 상태.
2. 환경·입력 — 실행 환경, 주요 모델·데이터·seed·표본 규모.
3. 구현 내용 — 생성·수정 파일과 핵심 설계 결정. 원본 보존 여부.
4. 실행 방법 — 재현 가능한 명령, 주요 인자, 단계 순서.
5. 결과 — 정량 지표와 대표 산출물. 직접 실행과 인용 수치를 구분.
6. 검증 — 수행한 테스트, 컴파일/정적 검사, 로그 완료 표식, 시각 검수.
7. 제약·남은 일 — 실패·차단·통계적 한계와 사용자 결정이 필요한 항목.

완료 게이트

• 보고서에 적는 수치와 상태는 결과 JSON·로그·파일을 직접 확인한 근거여야 한다.
• 테스트를 실행하지 못했으면 그 이유를 적고 테스트 완료로 표현하지 않는다.
• 실행 로그가 임시 경로에만 있으면 완료 처리하지 말고 프로젝트 폴더에 영구 보존한다.
• 보고서 작성 후 프로젝트의 작업내역.md가 있으면 보고서 경로와 한 줄 결과를 append한다.
• 최종 응답에는 보고서와 대표 산출물의 절대 경로 링크를 포함한다.
• 외부 문서 게시·전략 문서 편집은 관리자 범위이며, 사용자의 별도 지시와 승인 없이 수행하지 않는다.

프로젝트별 적용

• 프로젝트 루트·경로 규칙은 그 프로젝트의 문서(AGENTS.md·계획서)를 따른다.
  이 스킬에 특정 프로젝트 경로를 적지 않는다 — 다른 프로젝트에서 그대로 쓰기 위해서다.
• 그 프로젝트가 보고서에 반드시 넣으라고 정한 항목이 있으면 그것도 함께 지킨다.

측정·실험 계열에서는 대개 다음이 요구된다. 프로젝트가 명시하지 않았더라도 넣어 두면 좋다.

• 어떤 규약으로 측정했는가 (같은 이름의 지표라도 산정 방법이 다를 수 있다)
• 데이터를 줄였다면 그 조건과 seed
• 직접 실행인지 인용인지 — 섞이면 비교가 깨진다
• 표본이 작을 때의 통계적 한계

값만 적고 이 조건들을 빼면 다른 실험과 비교할 수 없는 숫자가 된다.

이력 (필수 기록)

• 생성일: 2026-08-20
• 업데이트 횟수: 2
• 최근 업데이트: 2026-08-27
• 사용 이력:
  • 2026-08-20 — 신규 생성. 실행자가 완료를 알리기 전에 검증 근거를 남기도록 강제.
  • 2026-08-27 — 위임 JSON 보고와의 관계를 2층 구조로 명문화. 두 산출물이 서로를
    참조하지 않아 어느 쪽이 정본인지 알 수 없던 상태였다.
  • 2026-08-27 — 공용 저장소로 이관. "특정 프로젝트 경로를 적지 않는다"고 써 둔 절
    바로 아래에 특정 과제의 요구 항목이 그대로 남아 있었다. 항목을 지우는 대신
    그것이 왜 필요한지(비교 가능한 숫자를 만들기 위한 조건)로 일반화했다.
    문자열 검색으로는 잡히지 않았고, 파일을 직접 열어 읽을 때 드러났다.