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

#### 1. 로그 목적

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

#### 2. 로그 상태값

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

- `[체크시작]`: 실제 단계 진입 시 한 번 기록한다.
- `[체크완료]`: 실제 결과 확인 시 한 번 기록한다.
- `[체크실패]`: 완료 조건을 충족하지 못했을 때 기록한다.
- `[예외추적]`: 기존 항목만으로 원인을 확인할 수 없을 때 실패 항목 아래에 임시 세부 점검을 추가한다.
- `[복구완료]`: 실패했던 기능이 실제 정상 복구됐을 때 기록한다.

#### 3. 로그 형식

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

예시:

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

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

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

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

- 체크 항목마다 후속 단계 의존 여부를 `blocking=true` 또는 `blocking=false`로 구분한다.
- `blocking=true` 실패 시 그 실패에 의존하는 후속 단계만 중단한다.
- `blocking=false` 실패 시 `다음단계=독립처리계속 / 실패항목=별도추적`으로 기록하고 독립 단계는 계속한다.
- 실패 이후 의존 단계를 성공처럼 기록하지 않는다.
- 코드 존재와 실제 정상동작을 구분한다.
- 실제 필요한 실행 로그와 `test_*` 결과가 모두 OK일 때만 완료로 기록한다.

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

- 처음부터 모든 상세 디버그 로그를 추가하지 않는다.
- 실패한 체크 항목에만 `AD-03-E01` 같은 예외 추적 ID를 추가한다.
- 원인이 해결되면 임시 예외 로그 유지 필요성을 검토하고 불필요하면 제거한다.

#### 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별 시작·완료·blocking 조건 정의
3. 필요한 최소 로그 구현
4. 실행 로그로 진행 위치 확인
5. 실패 항목만 예외 추적
6. 의존 체크 완료 뒤 다음 의존 단계 진행
7. 실제 로그가 없는 기능은 `[검증대기]` 유지

#### 9. 금지 사항

- 같은 정상 상태 반복 출력
- 코드 존재만으로 `[체크완료]` 기록
- 실제 결과 없이 완료 표시
- 내부 함수명과 원시 데이터 대량 출력
- 실패 지점과 무관한 전체 디버그 로그 상시 활성화
- 예외 없는 상태의 상세 추적 로그 상시 유지
- `blocking=false` 실패 때문에 독립적인 정상 처리까지 중단하는 방식
- `blocking=true` 실패 뒤 의존 단계를 성공으로 표시하는 방식