gitea-agent/harness/docs/project-structure

프로젝트 구조 작성 방법

프로젝트 구조 문서는 승인된 Discovery와 구현 결과를 근거로 저장소의 구성 원칙, 영역별 책임 및 의존 경계를 설명한다.

저장 위치

완성된 프로젝트 구조 문서는 대상 저장소 루트 기준 docs/project-structure.md에 저장한다. 파일이 이미 존재하면 별도 문서를 만들지 않고 이 정본 문서를 갱신한다.

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

작성 방법

1. TEMPLATE.md를 복사하고 섹션 순서를 유지한다.
2. 목적과 포함·제외 경계를 먼저 확정한다.
3. 디렉터리 구조의 H3 블록을 주요 영역 수만큼 복제하고 실제 저장소 기준 상대 경로를 기록한다.
4. 모든 ${lowercase_snake_case} placeholder를 실제 값으로 교체한다. ${stable_section_id}에는 고유한 소문자 케밥 표기법을 사용한다. 영역 이름이 바뀌어도 ID는 유지하며 삭제된 ID를 재사용하지 않는다.
5. 각 경로의 종류, 책임, 공개 진입점, 내부 구현 경계, 편집 정책 및 생성 주체를 기록한다. 행은 실제 경로 수만큼 복제한다.
6. 영역 간 의존마다 출발·대상 영역, 허용 여부, 규칙 및 공유 계약 위치를 기록한다. 역방향 또는 순환 의존은 명시적으로 금지한다.
7. 새 모듈과 파일의 배치, 이름·패키지 및 소스·테스트 대응 규칙을 기록한다.
8. 실제로 실행 가능한 구조 검사와 정적 분석 명령, 기대 결과 및 문서와 실제 트리의 정합성 확인 방법을 기록한다.

경로는 대상 저장소 루트 기준으로 작성하고 근거 없이 영역이나 규칙을 추측하지 않는다. 해당 사항이 없으면 없음으로 기록한다. 완성 문서에는 placeholder나 작성 안내 문구를 남기지 않는다.