### 기능 체크형 로그·단계별 작업 운영 원칙

#### 1. 로그 목적

* 로그는 상세 실행 내용을 계속 누적하는 용도로 사용하지 않는다.
* 로그는 기능별 체크리스트가 어디까지 실행됐는지 확인하는 용도로 사용한다.
* 사용자가 해당 기능의 로그만 전달해도 다음 단계 진행 가능 여부와 실패 지점을 판단할 수 있어야 한다.
* 기능명, 체크 항목, 결과, 오류 원인은 한국어를 우선한다.

#### 2. 로그 상태값

기능 체크 로그에는 아래 상태만 사용한다.

[체크시작]
[체크완료]
[체크실패]
[예외추적]
[복구완료]

* [체크시작]
  해당 기능 단계에 실제 진입했을 때 한 번 기록한다.

* [체크완료]
  해당 단계의 실제 결과가 확인됐을 때 한 번 기록한다.

* [체크실패]
  다음 단계 진행 조건을 충족하지 못했을 때 기록한다.
  실패 이후 단계는 실행하지 않거나 성공으로 기록하지 않는다.

* [예외추적]
  기존 체크 항목만으로 원인을 확인할 수 없을 때
  실패한 항목 아래에 임시 세부 점검 항목을 추가한다.

* [복구완료]
  실패했던 기능이 실제로 정상 복구됐을 때 기록한다.

#### 3. 로그 형식

[기능명][체크ID][상태] 한국어 체크 내용 / 핵심 결과

예시:

[자동다운로드][AD-01][체크시작] 자동 시작 상태 확인
[자동다운로드][AD-01][체크완료] 자동 시작 활성화
[자동다운로드][AD-02][체크완료] 대상=No003 계정=4eu_pick
[자동다운로드][AD-03][체크실패] 원본 미디어 URL 없음 / 다음점검=게시물 데이터 추출

#### 4. 중복 로그 방지

* 같은 실행에서 같은 기능, 체크 ID, 결과는 한 번만 기록한다.
* 상태 또는 핵심 값이 변경될 때만 다시 기록한다.
* 정상 health, 대기, 감시 상태를 초 단위 또는 짧은 주기로 반복 기록하지 않는다.
* 동일 오류는 최초 한 번만 기록한다.
* 동일 오류의 반복 횟수는 복구 또는 실행 종료 시 한 줄로 요약한다.
* 게시물이나 다운로드처럼 반복되는 작업은 cycle_id를 사용한다.
* 같은 cycle_id 안에서는 같은 체크 결과를 중복 기록하지 않는다.

#### 5. 단계 진행 기준

* 이전 체크 항목이 [체크완료]일 때만 다음 단계로 진행한다.
* [체크실패] 이후 단계를 성공처럼 기록하지 않는다.
* 코드에 기능이 존재하는 것과 실제 기능이 정상동작하는 것을 구분한다.
* 코드 반영만 된 기능은 완료가 아니다.
* 실제 필요한 실행 로그와 test_* 결과가 모두 OK일 때만 완료로 기록한다.

#### 6. 예외 추적 기준

* 처음부터 모든 상세 디버그 로그를 추가하지 않는다.
* 실패가 발생한 체크 항목에만 예외 추적 항목을 추가한다.
* 예외 추적 ID는 기존 체크 ID 아래에 추가한다.

예시:

AD-03 원본 URL 확인
AD-03-E01 게시물 데이터에 video_url 존재 확인
AD-03-E02 URL 만료 여부 확인
AD-03-E03 background 전달값 확인

* 원인이 해결되면 임시 예외 로그를 계속 유지할 필요가 있는지 검토한다.
* 불필요한 상세 추적 로그는 제거한다.

#### 7. ai_read 문서 연결

* ai_read.md
  현재 기능별 전체 체크리스트와 단계 진행 기준을 기록한다.

* ai_read_패치.md
  현재 실패한 체크 ID, 예외추적 항목, 다음 작업을 기록한다.

* ai_read_완료.md
  실제 테스트와 실행 로그로 완료된 체크 ID만 기록한다.

* ai_read_삭제.md
  반복 로그, 폐기된 체크, 다시 사용하면 안 되는 진단 방식을 기록한다.

* test_list.md
  체크 ID와 테스트 ID의 대응, 상태, 결과, 실패 원인, 다음 작업을 기록한다.

#### 8. 새 기능 작업 순서

1. 작업 전에 기능별 한국어 체크리스트를 작성한다.
2. 체크 ID별 시작 조건과 완료 조건을 정한다.
3. 필요한 최소 로그만 구현한다.
4. 실행 로그로 어디까지 진행됐는지 확인한다.
5. 실패한 항목만 예외 추적한다.
6. 해당 체크가 완료된 후에만 다음 단계로 이동한다.
7. 실제 로그가 없는 기능은 [검증대기]로 유지한다.

#### 9. 금지 사항

* 같은 정상 상태를 계속 반복 출력하는 로그
* 코드가 존재한다는 이유만으로 [체크완료]를 기록하는 방식
* 실제 결과가 없는데 완료로 표시하는 방식
* 내부 함수명과 원시 데이터만 대량으로 출력하는 방식
* 실패 지점과 관계없는 전체 디버그 로그를 항상 활성화하는 방식
* 예외가 없는 상태에서도 상세 추적 로그를 상시 남기는 방식