Initialize gitea-agent harness

2026-09-29 06:59:17 +00:00
commit c05b4226bf
20 changed files with 1840 additions and 0 deletions
@@ -0,0 +1,22 @@
+# 인터페이스 계약 작성 방법
+
+인터페이스 계약 문서는 승인된 Discovery와 구현 결과를 근거로 외부·내부 인터페이스의 호출 규칙을 설명한다.
+
+## 저장 위치
+
+완성된 인터페이스 계약 문서는 대상 저장소 루트 기준 `docs/interface-contract.md`에 저장한다. 파일이 이미 존재하면 별도 문서를 만들지 않고 이 정본 문서를 갱신한다.
+
+이 디렉터리의 [`README.md`](README.md)와 [`TEMPLATE.md`](TEMPLATE.md)는 하네스의 작성 규칙과 템플릿이며 대상 저장소에 저장하는 산출물이 아니다.
+
+## 작성 방법
+
+1. [`TEMPLATE.md`](TEMPLATE.md)를 복사하고 섹션 순서를 유지한다.
+2. 목적, 포함·제외 범위 및 인터페이스 사용 주체를 명시한다.
+3. `계약`의 H3 블록을 인터페이스 수만큼 복제하고 입력·출력·오류 행을 실제 계약 수만큼 복제한다.
+4. 모든 `${lowercase_snake_case}` placeholder를 실제 값으로 교체한다. `${stable_section_id}`에는 고유한 소문자 케밥 표기법을 사용한다. 인터페이스 이름이 바뀌어도 ID는 유지하며 삭제된 ID를 재사용하지 않는다.
+5. 각 인터페이스의 책임, 종류·프로토콜, 호출 대상, 버전, 호출 주체, 인증·권한을 기록한다.
+6. 입력·출력 필드와 오류 계약을 표에 기록한다. 값이 없으면 `없음`으로 기록한다.
+7. 기존 호출 방식, 버전 변경·폐기, 재시도·중복 처리 및 순서 보장에 대한 호환성 계약을 기록한다.
+8. 실제 구현과 일치하는 호출 예시와 정상·실패·경계 계약의 검증 방법을 기록한다. 예시에는 실제 credential이나 민감정보를 포함하지 않는다.
+
+근거 없이 인터페이스나 동작을 추측하지 않는다. 완성 문서에는 placeholder나 작성 안내 문구를 남기지 않는다.
@@ -0,0 +1,73 @@
+# ${interface_contract_title}
+
+## 목적과 범위
+
+${purpose}
+
+- 포함 범위: ${included_scope}
+- 제외 범위: ${excluded_scope}
+- 사용 주체: ${consumers}
+
+## 계약
+
+### ${stable_section_id} — ${interface_name}
+
+- 책임: ${responsibility}
+- 종류·프로토콜: ${interface_type_and_protocol}
+- 호출 대상·operation: ${target_and_operation}
+- 버전: ${version}
+- 호출 주체: ${caller}
+- 인증 방식: ${authentication}
+- 필요 권한: ${authorization}
+
+#### 입력
+
+| 필드 | 위치 | 타입 | 필수 여부 | 기본값 | 허용 값·형식 | 의미 | 민감정보 |
+|---|---|---|---|---|---|---|---|
+| `${input_field_name}` | ${input_location} | `${input_type}` | ${input_required_or_optional} | ${input_default_or_none} | ${input_constraints} | ${input_meaning} | ${input_sensitivity_or_none} |
+
+#### 출력
+
+| 필드 | 위치 | 타입 | 필수 여부 | 허용 값·형식 | 의미 | 민감정보 |
+|---|---|---|---|---|---|---|
+| `${output_field_name}` | ${output_location} | `${output_type}` | ${output_required_or_optional} | ${output_constraints} | ${output_meaning} | ${output_sensitivity_or_none} |
+
+#### 오류
+
+| 코드 | 분류 | 발생 조건 | 재시도 가능 여부 | 호출자 대응 | 실패 시 상태 변경 |
+|---|---|---|---|---|---|
+| `${error_code}` | ${error_class} | ${error_condition} | ${retryability} | ${caller_action} | ${state_change_or_none} |
+
+## 호환성
+
+- 유지할 기존 호출 방식: ${existing_call_compatibility}
+- 버전 변경 정책: ${versioning_policy}
+- 폐기 정책: ${deprecation_policy}
+- 재시도 계약: ${retry_contract}
+- 중복 처리 계약: ${idempotency_contract}
+- 순서 보장: ${ordering_guarantee}
+
+## 예시
+
+### ${example_id} — ${example_title}
+
+- 대상 인터페이스: `${target_interface_id}`
+
+#### 호출
+
+```text
+${request_or_call_example}
+```
+
+#### 결과
+
+```text
+${response_or_result_example}
+```
+
+## 검증
+
+- 정상 계약: ${success_contract_validation}
+- 실패 계약: ${failure_contract_validation}
+- 경계 계약: ${boundary_contract_validation}
+- 구현·스키마·예시 정합성: ${implementation_schema_example_consistency}