gitea-agent/harness/docs/runtime-flow

런타임 흐름 작성 방법

런타임 흐름 문서는 승인된 Discovery와 구현 결과를 근거로 시작 이벤트부터 종료 상태까지의 실행 단계, 상태 변경 및 실패 복구 계약을 설명한다.

저장 위치

완성된 런타임 흐름 문서는 대상 저장소 루트 기준 docs/runtime-flow.md에 저장한다. 파일이 이미 존재하면 별도 문서를 만들지 않고 이 정본 문서를 갱신한다.

이 디렉터리의 README.md와 TEMPLATE.md는 하네스의 작성 규칙과 템플릿이며 대상 저장소에 저장하는 산출물이 아니다.

작성 방법

1. TEMPLATE.md를 복사하고 섹션 순서를 유지한다.
2. 목적, 포함·제외 범위 및 흐름의 시작·종료 조건을 확정한다.
3. 흐름의 H3 블록을 독립 실행 흐름 수만큼 복제하고 단계 행을 실제 실행 순서대로 작성한다.
4. 모든 ${lowercase_snake_case} placeholder를 실제 값으로 교체한다. ${stable_section_id}에는 고유한 소문자 케밥 표기법을 사용한다. 흐름 이름이 바뀌어도 ID는 유지하며 삭제된 ID를 재사용하지 않는다.
5. 각 단계에 단계 ID, 실행 주체, 시작 조건·입력, 처리, 읽기·쓰기 상태, 외부 호출, 성공 시 다음 단계 및 실패 시 전이를 기록한다.
6. 각 실패에 추가 쓰기 중단 여부, 재시도, 중복 방지, 보상·수동 복구 및 최종 상태를 기록한다.
7. 동시 실행, 잠금·직렬화 단위, 순서 보장 및 충돌 처리를 기록한다.
8. 로그·지표·추적 신호와 correlation ID, 진단 속성 및 민감정보 제거 규칙을 기록한다.
9. 정상·실패·경계·동시성 흐름을 실제로 검증할 방법과 운영 진입점의 기대 결과를 기록한다.

단계 ID는 문서 안에서 고유해야 하며 모든 다음 단계와 실패 전이는 실제 단계 또는 명시된 종료 상태를 가리켜야 한다. 근거 없이 흐름이나 동작을 추측하지 않는다. 해당 사항이 없으면 없음으로 기록한다. 완성 문서에는 placeholder나 작성 안내 문구를 남기지 않는다.