# Content Harness
이 저장소는 자연어로 받은 콘텐츠 요청을 문서, 기술 그림, 이미지로 만드는 파이썬 프로젝트입니다. 세 하네스가 각 결과를 만들고 `workflow-runtime`이 요청 분기, 작업 순서, 검토 결과 취합, 게시 파일 생성을 맡습니다.
대상 독자:
- 저장소가 실제로 만드는 결과를 먼저 보고 싶은 개발자
- 예제를 실행하거나 하네스·계약·통합 코드를 수정하려는 개발자
## 검토를 마친 결과 예시
아래 세 파일은 `p6-all-harness-quality-executable-clean-architecture-20260717` 실행에서 검토와 통합 검증을 통과한 결과입니다. README에서 계속 볼 수 있도록 `docs/assets/readme-showcase/`로 옮겼습니다.
이미지 생성 — 후보 세 개와 독립 검토를 거쳐 고른 에디토리얼 이미지
|
기술 시각화 — 호출 관계와 소스·모듈 의존을 구분한 SVG
|
통합 문서 — 문서 작성, 이미지 생성, 기술 시각화 결과를 한 문서에 배치한 미리보기
[산출물 출처 기록](docs/assets/readme-showcase/provenance.yaml)에는 원본 실행 경로, 파일별 SHA-256 해시, 크기, 검토 상태가 들어 있습니다.
## 먼저 실행해 보기
### 준비 사항
기본 실행에는 `Python 3`, `PyYAML`, `jsonschema`가 필요합니다. `PNG` 검증과 미리보기에는 `Pillow`를 사용합니다. 기술 그림을 새로 렌더링하려면 `D2`가, `SVG`를 브라우저에서 미리 보려면 `Chrome` 또는 `Chromium`이 추가로 필요합니다. 저장소에는 이 도구들의 최소 버전이 적혀 있지 않습니다.
`pyproject.toml`, `requirements.txt` 같은 패키지 설정 파일도 없습니다. 따라서 README에서 확인되지 않은 설치 명령을 제시하지 않습니다. 필요한 도구를 준비한 뒤 저장소 루트에서 아래 명령을 실행합니다.
### 1. 예제 요청 검사
```bash
python3 -m packages.content_job_contract.validate_content_job examples/clean-architecture/content-job-request.yaml --repo-root .
```
2026-07-19 실행에서는 종료 코드 0으로 끝났습니다. 출력 없이 종료되면 예제 요청이 현재 계약을 통과한 것입니다.
### 2. 작업 계획 확인
```bash
python3 -m packages.workflow_runtime.content_runtime front-door --workflow-request examples/clean-architecture/workflow-request.content-job.yaml --repo-root .
```
2026-07-19 실행에서는 종료 코드 0과 `primary_capability: document-writing` 계획을 확인했습니다. 이 명령은 작업 계획만 만들며 외부 생성 도구를 호출하지 않습니다.
## 기능별 책임
### 문서 작성 — `document-writing`
독자, 글의 순서, 근거 연결, 그림이 필요한 위치를 정합니다. 요청 명세, 내용 명세, 서사 계획, 게시 초안, 그림 요청을 만들지만 원문을 덮어쓰거나 렌더러를 고르지는 않습니다.
### 기술 시각화 — `technical-visualization`
코드와 문서에서 확인한 관계를 의미 모형으로 만들고 D2로 렌더링합니다. 현재 `dependency-graph`와 `runtime-sequence`를 만들 수 있습니다. 기술 내용과 화면 표현을 서로 다른 검토자가 승인해야 산출물 묶음이 `accepted`가 됩니다.
### 이미지 생성 — `image-generation`
사진, 일러스트, 재질, 분위기처럼 유기적인 래스터 이미지를 만듭니다. 후보 세 개를 비교해 하나를 고르고, 필요한 경우 한 번만 부분 수정합니다. 정확한 아키텍처 관계, 차트, 상태 전이, 긴 본문은 이 기능으로 만들지 않습니다.
### 작업 실행과 게시 — `workflow-runtime`, `integrations`
`workflow-runtime`은 요청 검사, 분기, 작업 순서, 재시도, 결과 취합을 담당합니다. 세 하네스는 서로를 직접 호출하지 않습니다.
`Markdown`, `Slides`, `HTML` 어댑터는 작업 실행기가 확정한 게시 자료만 받습니다. 어댑터가 내용이나 생성 도구를 다시 고르지는 않습니다.
## 요청이 결과가 되는 과정
파일 계약은 `ContentJobRequest` → `Content Manifest` → `Narrative Plan` → `Visual Request` → `ArtifactSet` → 게시 자료 순서로 이어집니다. 각 단계는 다음 단계가 받아도 되는 정보와 검토 상태를 제한합니다.
그림 요청이 기술 관계만 포함하면 `technical-visualization`, 이미지 표현만 포함하면 `image-generation`으로 보냅니다. 둘 다 필요하면 `workflow-runtime`이 두 결과를 합치는 작업 순서를 만듭니다. 신호가 없거나 서로 충돌하면 실행을 막습니다.
```mermaid
flowchart LR
A["자연어 요청"] --> B["요청 명세"]
B --> R{"workflow-runtime
분기 · 작업 순서 · 검토"}
R --> D["document-writing
문서 초안"]
R --> T["technical-visualization
기술 그림"]
R --> I["image-generation
이미지"]
T --> H["혼합 합성"]
I --> H
D --> P["검토된 게시 자료"]
T --> P
I --> P
H --> P
P --> O["Markdown · Slides · HTML"]
```
`workflow-runtime`이 세 하네스로 요청을 나누고, 검토를 마친 결과를 게시 자료로 합칩니다.
구조 검사만 통과한 결과는 바로 게시하지 않습니다. 문서는 지정된 검토를 마쳐야 하고, 기술 그림과 이미지는 `accepted`이면서 통합 준비 상태여야 합니다.
## 저장소 구성과 변경 위치
| 경로 | 맡는 일 | 이럴 때 먼저 확인 |
| --- | --- | --- |
| `.agents/`, `.codex/` | 도구가 하네스를 찾게 하는 얇은 연결부 | 도구별 진입점 변경 |
| `harnesses/` | 문서·기술 그림·이미지 생성 정책과 구현 | 생성 방식이나 검토 규칙 변경 |
| `packages/` | 파일 계약, 공통 검사, 작업 실행기 | 명세 구조나 실행 순서 변경 |
| `integrations/` | 확정된 게시 자료를 `Markdown`·`Slides`·`HTML`로 변환 | 출력 형식 변경 |
| `tests/` | 계약·실행·실패 조건·저장소 구성 검사 | 동작 변경과 회귀 검사 추가 |
| `examples/` | 버전 관리되는 실행 예제 | 재현 가능한 예제 추가 |
| `benchmarks/` | 평가 자료와 판정 결과 | 품질 기준이나 비교 자료 변경 |
| `runs/` | 버전 관리하지 않는 실행 기록 | 실행 재개와 실패 원인 확인 |
정본 의존 방향은 도구 연결부 → 하네스 → 공통 계약입니다. `workflow-runtime`은 등록 파일을 통해 하네스를 실행하고, 확정된 게시 자료만 `integrations`로 보냅니다.
전체 계약 사슬과 혼합 합성 경계는 [ARCHITECTURE.md](ARCHITECTURE.md)에 정리돼 있습니다.
## 검증
아래 결과는 2026-07-19에 저장소 루트에서 확인했습니다.
### 내용 명세
```bash
python3 -m packages.content_contract.validate_content examples/clean-architecture/content-manifest.yaml --repo-root .
```
결과는 `VALID`, 종료 코드 0입니다.
### 기술 그림 산출물 묶음
```bash
python3 -m packages.artifact_contract.validate_artifact_set examples/clean-architecture/artifact/attempt-01/artifact-set.yaml --request examples/clean-architecture/visual-request.yaml
```
결과는 `VALID`, 종료 코드 0입니다. 이 명령은 버전 관리되는 계약 예시를 검사하며 새 그림을 렌더링하지 않습니다.
### 저장소 구성
```bash
python3 -m unittest tests.conformance.test_repository_layout
```
구성 검사 18개가 통과했습니다.
### 전체 테스트
```bash
python3 -m unittest discover -s tests -p 'test_*.py'
```
전체 테스트 300개가 615.249초에 통과했습니다. 외부 자료와 별도 검토 파일을 넣어야 하는 종단 간 작업은 이 결과와 구분해야 합니다.
외부 입력을 준비하는 방법은 [종단 간 작업 안내](tests/end-to-end/README.md)에 있습니다.
## 현재 한계
- **설치 절차:** 패키지 설정 파일과 버전 고정값이 없어 하나의 재현 가능한 설치 명령을 제공하지 못합니다.
- **실행 기록:** `runs/`는 버전 관리 대상이 아닙니다. 재사용할 예시는 `docs/`나 `examples/`로 옮기고 출처를 함께 기록해야 합니다.
- **외부 입력:** 일부 종단 간 작업에는 외부 Java·Gradle 저장소, 원문, 완료된 전문가 검토 파일이 필요합니다.
- **평가 자료:** 문서 작성과 이미지 생성 평가는 자료 구조만 정의돼 있고 결과는 아직 없습니다. 기술 시각화 비교에도 실행하지 않은 조건과 사람 선호 판정이 남아 있습니다.
- **혼합 합성:** `d2-svg-layer-compositor`는 자동 검사에 통과했지만 사람 검토가 남아 있어 정식 렌더러로 분류하지 않습니다.
## 더 읽을 문서
- [전체 설계](ARCHITECTURE.md) — 계층, 계약, 분기, 검토 권한
- [문서 색인](docs/README.md) — 현재 문서와 구현 이력의 구분
- [실행 작업공간](runs/README.md) — 새 실행 할당, 재개, 결과 게시
- [문서 작성 하네스](harnesses/document-writing/README.md)
- [기술 시각화 하네스](harnesses/technical-visualization/README.md)
- [이미지 생성 하네스](harnesses/image-generation/README.md)
- [작업 실행기](packages/workflow-runtime/README.md)
- [Clean Architecture 예제](examples/clean-architecture/)
- [평가 자료](benchmarks/technical-visualization/README.md) · [이미지 품질](benchmarks/image-quality/README.md) · [혼합 합성](benchmarks/hybrid-composition/README.md)