Agent Architecture Docs — README

AX팀 agent 아키텍처 문서의 진입점. 문서 체계, 관리 규칙, 활용 방법.

---

빠른 시작

전제: Claude Code와 Docker가 설치되어 있다. cleanharness(이 레포)와 새 프로젝트 폴더는 별도로 분리한다.

workspace/
  ├── cleanharness/    ← 이 레포. 건드리지 않음
  └── my-project/      ← 새 프로젝트 폴더 (여기서 Claude Code 실행)

1단계. 프로젝트 폴더 생성 및 CLAUDE.md 복사

mkdir my-project && cd my-project
cp ../cleanharness/harness/init/project_templates/CLAUDE.md .

복사한 CLAUDE.md 상단의 CLEANHARNESS_PATH 값을 cleanharness의 실제 경로로 수정한다.

# 예시 (상대 경로)
CLEANHARNESS_PATH: ../cleanharness

2단계. .env 작성

cp ../cleanharness/harness/init/.env.example .env

.env를 열어 API 키를 입력한다. 이 파일은 사람이 직접 작성해야 한다.

3단계. Claude Code 실행

claude

CLAUDE.md가 자동 로딩된다. 이후는 Claude가 안내한다:

새 프로젝트 시작하고 싶어

Claude가 누락 항목(.claude/agents/, projects/, Dockerfile 등)을 확인하고 CLEANHARNESS_PATH에서 복사한다 (CLAUDE.md §2.0 참조). .env만 사람이 직접 작성하면 된다.

4단계. 명세 작성 → 실행 세션

환경 초기화 후 Claude가 명세 준비 모드(CLAUDE.md §2.1)로 진입한다.

• doc/ 폴더에 요구사항 문서(.pdf 등)가 있으면 Claude가 자동으로 발견하고 보조 작성을 제안한다
• 명세 완성 + Spec Reviewer PASS 후 실행 세션(CLAUDE.md §2.2)에 진입한다

---

문서 지도

cleanharness/                        ← 이 레포
  ├─ README.md                       : 본 파일. 문서 체계 안내
  ├─ CLAUDE.md                       : Claude Code 자동 로딩. Identity + 행동 양식
  └─ harness/
      ├─ [핸드북]
      ├─ handbook/
      │   ├─ handbook.md             : 설계 원칙 + workflow 뼈대 개요 + 챕터 목차
      │   ├─ workflow/               : 공통 workflow 상세 (개발 맥락 기본값)
      │   │   ├─ subagents_and_review.md
      │   │   ├─ operations.md
      │   │   └─ failures.md
      │   └─ context/                : 맥락별 오버라이드
      │       ├─ development.md      : 개발 맥락
      │       └─ on_service.md       : 온서비스 에이전트 (스켈레톤)
      │
      ├─ [경험치 / 카탈로그]
      ├─ skills/
      │   ├─ skills.md               : 재사용 도구 인덱스 + SKILL.md 포맷 규칙
      │   └─ {skill_name}/SKILL.md
      ├─ failure_catalog.md          : 사후 오답노트
      │
      ├─ [교차 이력]
      ├─ decisions.md                : ADR 누적 로그
      └─ open_questions.md           : 미해결 가설
      │
      └─ init/                       : 새 프로젝트 초기화 템플릿
          ├─ infra.md                : 사내망 제약 (ePrism SSL, Docker 환경)
          ├─ Dockerfile
          ├─ docker-compose.yml
          ├─ .env.example
          ├─ ePrism-SSL-ROOT-CA.crt
          ├─ project_templates/      : 프로젝트 문서 최소 템플릿
          │   ├─ project_specification.md
          │   ├─ overrides.md
          │   └─ job_progress/
          │       ├─ job_progress.md
          │       └─ metrics.md
          └─ agent_templates/        : 역할별 .claude/agents/ 정의 파일 템플릿
              ├─ worker.md
              ├─ reviewer_a.md
              ├─ reviewer_b.md
              ├─ reviewer_c.md
              ├─ tester.md
              ├─ meta_supervisor.md
              ├─ spec_writer.md
              └─ spec_reviewer.md

프로젝트 실행 파일 — 프로젝트 시작 시 생성 (프로젝트 루트)
  ├─ project_specification.md         : harness/init/project_templates/project_specification.md 복사 후 작성
  ├─ Dockerfile                        : harness/init/Dockerfile 복사
  ├─ docker-compose.yml               : harness/init/docker-compose.yml 복사
  ├─ ePrism-SSL-ROOT-CA.crt           : harness/init/ 복사
  └─ projects/
      ├─ overrides.md                  : harness/init/project_templates/overrides.md 복사 후 작성
      ├─ job_progress.md               : harness/init/project_templates/job_progress/job_progress.md 복사
      └─ job_progress/
          ├─ log/                      : 세션 중 오케스트레이터 생성
          └─ metrics.md                : harness/init/project_templates/job_progress/metrics.md 복사

---

문서별 특성

문서	독자	수정 빈도	수정 권한	agent 주입
CLAUDE.md	모든 agent	낮음	팀 합의	자동 로딩
handbook/handbook.md	신규 팀원, 타 팀	낮음	팀 합의	오케스트레이터 컨텍스트
handbook/workflow/*	오케스트레이터 설정자	중간	팀 합의	필요 subagent
handbook/context/*	프로젝트 오케스트레이터	중간	팀 합의	해당 맥락 프로젝트
decisions.md	6개월 뒤의 자신	Append-only	오케스트레이터(승인 게이트), 과거 수정 금지	사람만
open_questions.md	실험/파일럿 설계자	높음	자유 추가	사람만
skills/skills.md	Worker	중간	도구 소유자	필요 시점
failure_catalog.md	Reviewer-B	높음	오케스트레이터(승인 게이트)	Reviewer-B 필수

---

활용 방법

신규 팀원 온보딩

1. README.md (본 문서) — 지도 파악
2. CLAUDE.md — 팀 identity
3. handbook/handbook.md — 원리 + 뼈대 개요
4. handbook/workflow/ 챕터 — 상세
5. init/infra.md — 사내망 제약
6. decisions.md — 관심 ADR 탐색
7. open_questions.md — 현재 고민 파악

새 프로젝트 시작

1. 프로젝트 맥락 판정 (개발 도구/플랫폼 → development, 배포 에이전트 → on_service)
2. .env 작성 (API 키). init/.env.example 참조
3. Claude Code 실행: "새 프로젝트 시작하고 싶어" → CLAUDE.md §2.0 환경 초기화 진행

파일럿 결과 반영

1. 관찰을 open_questions.md 해당 Q에 기록
2. 결론 도달 시 decisions.md에 신규 ADR (해당 Q는 open_questions에서 제거)
3. ADR에 따라 handbook/workflow/ 또는 handbook/context/ 업데이트 (버전 증분)
4. 원리 수준 변화면 handbook/handbook.md 수정 (드물어야 정상)

타 팀 공유

• handbook/handbook.md만 떼어 공유 — 타 팀의 진입점
• CLAUDE.md와 handbook/workflow/는 AX팀 사례로 참조 제공
• 타 팀은 자기 CLAUDE.md와 자기 workflow를 별도 작성

세션 종료 후행 액션

CLAUDE.md §2.5 참조.

---

버전 관리

문서	정책
handbook/handbook.md	변경 시 날짜 기록. 변경은 드물어야 함
handbook/workflow/*	Semver. major=뼈대 변경, minor=필드 추가, patch=오타
handbook/context/*	Semver. 상위 workflow와 별도
CLAUDE.md	날짜 기록. 큰 변경은 ADR 동반
decisions.md	각 ADR 번호. Append-only
open_questions.md	최종 업데이트 날짜만
프로젝트 문서	프로젝트 수명과 연동

Baseline 버전 고정

프로젝트는 시작 시점 workflow 버전을 명시적으로 고정. Baseline 수정이 기존 프로젝트에 자동 전파되지 않도록 한다.

---

문서 체계 수정 규칙

반드시 업데이트해야 하는 경우: 신규 문서 추가/폐기, 문서 간 관계 변경, 수정 권한 변경, Baseline 버전 정책 변경, 문서 지도 구조 변경

업데이트 불요: 단순 내용 수정, 오타 수정, 예시 추가/변경

---

현재 상태

본 문서 체계는 논리적 가설 집합이며 파일럿 검증 대기 중이다. 파일럿 0회. 근간 가정 다수가 미검증. 자세한 미해결 항목은 open_questions.md 참조.