운영 기록을 남기고 개선하기

자동매매 학습 프로젝트는 코드가 한 번 실행되었다고 끝나지 않는다. 데이터를 제때 읽었는지, 신호가 없었던 것인지 계산이 실패한 것인지, 현금·수량 기록이 맞는지 매일 구분해야 한다. 이번 장에서는 그 판단을 다음 실행과 연결하는 운영 기록을 만든다.

이 책의 운영 대상은 외부 주문이 없는 auto-trading-lab의 로컬 paper 환경이다. 아래 기록과 손익은 모두 가상 예시다. 운영 검토의 목적은 수익을 약속하거나 매매 결정을 대신하는 것이 아니라 실행 상태와 변경 근거를 보존하는 것이다.

1. 실행 결과와 운영 판단을 연결하기

paper_runs에는 프로그램이 실제로 한 일을 기록하고, operation_notes에는 사람이 그 결과를 어떻게 판단했는지 적는다. “오늘 이상 없음”이라는 메모만 남기면 어떤 데이터와 원장을 봤는지 알 수 없다. 실행 식별자와 증거 경로를 함께 기록한다.

판단과 사실이 다르면 사실을 먼저 확인한다. 예를 들어 로그에 오류가 없더라도 해당 거래일의 실행 행이 없다면 “문제 없음”이 아니라 “미실행 또는 기록 유실 의심”이다.

2. 하루 점검 순서를 고정하기

데이터 → 계산 → 의도 → 체결 → 원장 → 오류 → 다음 조치 순서로 점검한다. 매일 같은 순서로 보면 상류 단계의 실패가 하류의 신호 없음으로 위장하는 것을 줄일 수 있다.

1. 처리할 business_date와 데이터 확정 시각을 확인한다.
2. 대상 종목 수, 원본 행 수, 누락·가격 이상을 확인한다.
3. CCI 계산 대상과 결측 사유, 상향 돌파 신호 수를 확인한다.
4. 주문 의도·제외 사유와 기존 의도키 충돌을 확인한다.
5. 가상 체결과 예약현금, 보유 수량을 대조한다.
6. 실행 상태와 오류·중단·복구 기록을 확인한다.
7. 다음 실행을 허용할지 판단하고 근거를 적는다.

신호 0건은 정상일 수 있다. 하지만 계산 대상 0건, 수집 실패 200건, 신호 0건을 같은 정상 결과로 표시하면 안 된다. 기대 대상 수와 실제 처리 수를 함께 보고한다.

3. 운영 메모의 최소 구조 만들기

operation_notes에는 다음 필드를 둔다. 사실을 보정해야 할 때는 기존 메모를 지우지 않고 새 메모에서 이전 기록을 참조한다.

CREATE TABLE operation_notes (
  note_id CHAR(36) PRIMARY KEY,
  business_date DATE NOT NULL,
  run_id VARCHAR(80) NOT NULL,
  environment VARCHAR(20) NOT NULL,
  category VARCHAR(40) NOT NULL,
  decision VARCHAR(40) NOT NULL,
  evidence_path VARCHAR(255) NOT NULL,
  summary TEXT NOT NULL,
  follow_up TEXT,
  created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
) ENGINE=InnoDB;

environment는 local_paper로 명시한다. 계좌번호나 토큰을 증거 경로와 메모에 넣지 않는다. 하루에 여러 실행이 있으면 각 실행과 일일 종합 메모를 연결해 재시도가 누락되지 않게 한다.

business_date=2026-06-09 environment=local_paper
run_id=demo-paper-12 state=COMPLETED
targets=5 calculated=5 signals=0 pending_orders=0
cash_difference=0.00 quantity_difference=0
decision=CONTINUE_LOCAL_PAPER
summary=데이터 확정·계산·원장 대조 완료, 신규 신호 없음

이 예시는 보고 형식이며 실제 프로젝트가 해당 날짜에 실행되었다는 증거가 아니다. 실제 보고서는 DB와 로그에서 읽은 값으로 생성한다.

4. 기술 실패·운영 차단·전략 결과를 구분하기

기술 실패는 프로그램이 정해진 처리를 수행하지 못한 경우다. 운영 차단은 미확정 데이터나 중단 파일처럼 미리 정한 조건에 따라 멈춘 경우다. 전략 결과는 프로그램이 정상 처리했지만 가상 손익이 좋거나 나빴던 경우다.

손실을 모두 버그로 보거나 오류를 모두 전략 탓으로 돌리면 원인을 찾기 어렵다. 먼저 같은 입력의 수동 계산과 상태 전이를 확인하고, 처리 자체가 정확한 경우에 전략 검토 후보로 분류한다.

5. 장애 기록은 원인보다 증거부터 적기

장애 발생 시 첫 기록에는 관측 사실, 영향 범위, 마지막 정상 시각, 중단 상태를 적는다. 원인을 아직 모르면 UNKNOWN이라고 쓴다. “아마 네트워크 문제”라는 추정을 확정 원인처럼 기록하지 않는다.

incident_id=demo-incident-03 severity=BLOCKING
observed=현금 원장 합계와 계정 현금 차이 50.00
affected_run=demo-paper-13 last_known_good=demo-paper-12
new_processing=BLOCKED root_cause=UNKNOWN
evidence=outputs/incidents/demo-incident-03/
next_action=체결별 수수료 정산 사건과 반올림 정책 대조

기록을 맞추려고 원장 행을 삭제하거나 현금을 임의로 바꾸지 않는다. 불변 체결과 현금 사건으로 기대 상태를 다시 계산한다. 정정이 필요하면 수정 사유·원본 참조·정정 사건을 남기고 대조를 다시 수행한다. 새 상태가 맞았다는 근거를 복구 기록에 연결한다.

운영 로그를 읽을 때는 프로젝트의 UTF-8 로그 도구가 있으면 그것을 사용하고, PowerShell에서는 Get-Content -Encoding UTF8을 사용한다. 인코딩에 따른 표시 차이는 Microsoft 공식 문서에서 확인할 수 있다.

6. 전략 변경을 실험 단위로 관리하기

손실 한 건을 본 직후 CCI 기준을 바꾸지 않는다. 바꾸고 싶은 이유를 먼저 가설로 적고, 현재 기준 실행을 보관한다. CCI 기간·돌파 수준·진입·청산·비용 중 무엇을 바꾸는지 한 번에 구분할 수 있어야 한다.

{
  "change_id": "demo-change-02",
  "status": "PROPOSED",
  "baseline_version": "cci20_cross_up_m100_v1",
  "candidate_version": "cci20_cross_up_m100_v2_experiment",
  "hypothesis": "가격 누락 처리 변경이 미완료 분류를 더 정확하게 만드는가",
  "changed_component": "missing_session_classification",
  "evaluation_dataset": "fixture-v2",
  "paper_restart_required": true,
  "live_permission": false
}

이 예시는 수익 규칙 변경보다 데이터 처리 개선을 먼저 비교한다. 실제 전략 조건을 실험하더라도 가설, 평가 기간, 비용 가정, 제외 기준을 결과를 보기 전에 정한다. 여러 후보를 시도했다면 가장 좋은 하나뿐 아니라 시도한 후보 수와 탈락 결과도 남긴다.

변경 상태는 PROPOSED → UNDER_REVIEW → SIMULATION_CHECKED → PAPER_CHECKED → ACCEPTED로 관리한다. 실패나 보류는 REJECTED, DEFERRED로 남긴다. ACCEPTED는 이 책의 로컬 학습 기준에 반영했다는 뜻이며 실전 전송 허가가 아니다.

7. 주간 리뷰에서 처리 품질과 결과를 나누기

주간 리뷰에는 예정 세션 수와 실제 실행 수, 차단 횟수와 사유, 오류 재발, 복구 시간, 미해결 항목을 먼저 적는다. 그다음 비용 후 가상 손익과 포지션 변화를 본다. 단순 수익률 표만으로 운영 상태를 판단하지 않는다.

4회 완료를 80% 성공이라고만 표현하면 정상적인 데이터 보호 차단과 기술 실패가 섞인다. 차단의 이유와 적절성을 함께 해석한다. 예시의 횟수는 운영 품질 기준을 설명할 뿐 실제 서비스 안정성을 입증하지 않는다.

8. 백업은 복구 시험까지 수행하기

보관 대상은 소스 버전, 비밀값 없는 설정 예제, DB 스키마, 원장 데이터, 실행 식별자와 검토 기록이다. 접근 권한이 필요한 원본 데이터와 비밀 설정은 별도 보호하고 공개 저장소나 위키에 올리지 않는다.

복구 시험은 빈 테스트 DB에서 수행한다. 백업을 복원한 뒤 원장 건수, 마지막 run_id, 현금·수량 대조, 미완료 주문과 예약액을 확인한다. 복구본을 실제 반복 스케줄러에 연결하지 않도록 환경 이름과 DB 이름을 구분한다.

기록의 해시를 비교하면 파일 변경을 확인하는 데 도움이 되지만, 해시가 같다는 이유로 데이터의 정확성까지 보장되지는 않는다. 해시 계산은 Python 공식 hashlib 문서를 참고하고, 기능 대조와 함께 사용한다.

9. Codex에 운영 증거를 요약하도록 요청하기

이번 주 local_paper 운영을 읽기 전용으로 점검해줘.
paper_runs·주문·체결·현금 원장·operation_notes를 run_id로 연결해.
예정 세션, 완료, 정상 차단, 기술 실패, 재시도, 복구를 구분해.
현금·수량 불일치와 미해결 장애를 먼저 보고하고 근거 경로를 적어줘.
가상 손익은 비용과 평가 시각을 표시하고 실제 성과처럼 표현하지 마.
전략 변경 로그 없이 달라진 설정이 있는지 확인해.
파일·DB 수정, 실제 주문, 외부 메시지 발송은 수행하지 마.

읽기 전용 검토가 끝나면 해결할 항목 하나를 정해 별도 수정 작업으로 이어간다. 수정 시 기존 결과를 보존하고 관련 시뮬레이션·페이퍼·차단 시험을 다시 확인한다. 모르는 값을 추정해 보고서 빈칸을 채우지 않는다.

10. 완료 기준과 계속 유지할 원칙

이 장의 완료 기준은 하루 메모가 실행·증거와 연결되고, 장애와 전략 관찰이 구분되며, 변경이 검토 단계를 거치고, 복구 시험 결과가 남는 것이다. 처음 한 번 작성한 운영 문서를 영구적으로 완료된 상태로 보지 않는다.

데이터를 확인하고, 규칙을 기록하고, 이상 상태에서 멈추고, 근거가 있을 때만 변경한다. 이 절차를 반복할 수 있는 로컬 학습 시스템이 이 책의 최종 산출물이다. 실제 시장 연결과 운영 판단은 별도의 검토 과제로 남긴다.