readme-haness/runs/image-haness/20260719-reader-first-korean/README.candidate.md

Content Harness

이 저장소는 자연어로 받은 콘텐츠 요청을 문서, 기술 그림, 이미지로 만드는 파이썬 프로젝트입니다. 세 하네스가 각 결과를 만들고 workflow-runtime이 요청 분기, 작업 순서, 검토 결과 취합, 게시 파일 생성을 맡습니다.

대상 독자:

• 저장소가 실제로 만드는 결과를 먼저 보고 싶은 개발자
• 예제를 실행하거나 하네스·계약·통합 코드를 수정하려는 개발자

검토를 마친 결과 예시

아래 세 파일은 p6-all-harness-quality-executable-clean-architecture-20260717 실행에서 검토와 통합 검증을 통과한 결과입니다. README에서 계속 볼 수 있도록 docs/assets/readme-showcase/로 옮겼습니다.

이미지 생성 — 후보 세 개와 독립 검토를 거쳐 고른 에디토리얼 이미지

기술 시각화 — 호출 관계와 소스·모듈 의존을 구분한 SVG

_{통합 문서 — 문서 작성, 이미지 생성, 기술 시각화 결과를 한 문서에 배치한 미리보기}

산출물 출처 기록에는 원본 실행 경로, 파일별 SHA-256 해시, 크기, 검토 상태가 들어 있습니다.

먼저 실행해 보기

준비 사항

기본 실행에는 Python 3, PyYAML, jsonschema가 필요합니다. PNG 검증과 미리보기에는 Pillow를 사용합니다. 기술 그림을 새로 렌더링하려면 D2가, SVG를 브라우저에서 미리 보려면 Chrome 또는 Chromium이 추가로 필요합니다. 저장소에는 이 도구들의 최소 버전이 적혀 있지 않습니다.

pyproject.toml, requirements.txt 같은 패키지 설정 파일도 없습니다. 따라서 README에서 확인되지 않은 설치 명령을 제시하지 않습니다. 필요한 도구를 준비한 뒤 저장소 루트에서 아래 명령을 실행합니다.

1. 예제 요청 검사

python3 -m packages.content_job_contract.validate_content_job examples/clean-architecture/content-job-request.yaml --repo-root .

2026-07-19 실행에서는 종료 코드 0으로 끝났습니다. 출력 없이 종료되면 예제 요청이 현재 계약을 통과한 것입니다.

2. 작업 계획 확인

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이 두 결과를 합치는 작업 순서를 만듭니다. 신호가 없거나 서로 충돌하면 실행을 막습니다.

flowchart LR
    A["자연어 요청"] --> B["요청 명세"]
    B --> R{"workflow-runtime<br/>분기 · 작업 순서 · 검토"}
    R --> D["document-writing<br/>문서 초안"]
    R --> T["technical-visualization<br/>기술 그림"]
    R --> I["image-generation<br/>이미지"]
    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에 정리돼 있습니다.

검증

아래 결과는 2026-07-19에 저장소 루트에서 확인했습니다.

내용 명세

python3 -m packages.content_contract.validate_content examples/clean-architecture/content-manifest.yaml --repo-root .

결과는 VALID, 종료 코드 0입니다.

기술 그림 산출물 묶음

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입니다. 이 명령은 버전 관리되는 계약 예시를 검사하며 새 그림을 렌더링하지 않습니다.

저장소 구성

python3 -m unittest tests.conformance.test_repository_layout

구성 검사 18개가 통과했습니다.

전체 테스트

python3 -m unittest discover -s tests -p 'test_*.py'

전체 테스트 300개가 615.249초에 통과했습니다. 외부 자료와 별도 검토 파일을 넣어야 하는 종단 간 작업은 이 결과와 구분해야 합니다.

외부 입력을 준비하는 방법은 종단 간 작업 안내에 있습니다.

현재 한계

• 설치 절차: 패키지 설정 파일과 버전 고정값이 없어 하나의 재현 가능한 설치 명령을 제공하지 못합니다.
• 실행 기록: runs/는 버전 관리 대상이 아닙니다. 재사용할 예시는 docs/나 examples/로 옮기고 출처를 함께 기록해야 합니다.
• 외부 입력: 일부 종단 간 작업에는 외부 Java·Gradle 저장소, 원문, 완료된 전문가 검토 파일이 필요합니다.
• 평가 자료: 문서 작성과 이미지 생성 평가는 자료 구조만 정의돼 있고 결과는 아직 없습니다. 기술 시각화 비교에도 실행하지 않은 조건과 사람 선호 판정이 남아 있습니다.
• 혼합 합성: d2-svg-layer-compositor는 자동 검사에 통과했지만 사람 검토가 남아 있어 정식 렌더러로 분류하지 않습니다.

더 읽을 문서

• 전체 설계 — 계층, 계약, 분기, 검토 권한
• 문서 색인 — 현재 문서와 구현 이력의 구분
• 실행 작업공간 — 새 실행 할당, 재개, 결과 게시
• 문서 작성 하네스
• 기술 시각화 하네스
• 이미지 생성 하네스
• 작업 실행기
• Clean Architecture 예제
• 평가 자료 · 이미지 품질 · 혼합 합성