패키지 구조

agent_harness/          # Python 패키지
├── models.py           # 데이터 모델 (Item, Category, Preset, Manifest)
├── store.py            # 저장소 발견 & 콘텐츠 로딩
├── installer.py        # 설치 로직 (파일 복사 + manifest 업데이트)
├── block.py            # CLAUDE.md managed block 삽입/교체
├── marketplace.py      # build-marketplace 로직
└── adapters/
    ├── base.py         # 추상 기반 클래스
    ├── claude_code.py  # Claude Code 어댑터 (CLAUDE.md)
    ├── codex.py        # OpenAI Codex 어댑터 (AGENTS.md)
    └── opencode.py     # OpenCode 어댑터 (AGENTS.md)

핵심 모듈 역할

전체 실행 흐름

Store 발견 로직 (find_store_root)

TUI가 콘텐츠 저장소를 찾는 방법입니다:

1. 환경변수 AGENT_HARNESS_STORE가 설정되어 있으면 그 경로를 사용
2. 설정 안 되어 있으면 현재 디렉터리부터 위로 walk-up — rules/와 skills/ 폴더가 함께 있는 디렉터리 탐색
3. 그것도 없으면 패키지 설치 위치에서 찾기 (패키지와 함께 배포된 기본 콘텐츠)

# 수동 설정 (다른 경로에 있는 store 사용)
export AGENT_HARNESS_STORE=/path/to/your/store
agent-harness-tui

데이터 모델

# models.py
@dataclass
class Item:
    kind: str        # "rule" | "skill"
    category: str    # "workflow", "auth", ...
    id: str          # "plan-first", "azure-ad-sso-flask"
    name: str        # "Plan before code"
    description: str
    path: Path       # 실제 파일 경로

def item_key(item: Item) -> str:
    return f"{item.kind}:{item.category}/{item.id}"
    # "rule:workflow/plan-first"

@dataclass
class Manifest:
    items: list[ManifestItem]

    def union_items(self, new_items: list[Item]) -> "Manifest":
        # 기존 + 신규를 item_key로 병합 (중복 제거)
        # 같은 key면 신규로 메타데이터 업데이트
        ...

block.py — Managed Block 로직

CLAUDE.md에 managed block을 삽입하거나 기존 블록을 교체합니다.

# block.py
START = "<!-- AGENT-HARNESS_START -->"
END   = "<!-- AGENT-HARNESS_END -->"

def upsert_block(claude_md_path: Path, new_content: str) -> None:
    existing = claude_md_path.read_text()
    wrapped = wrap(new_content)           # START...END로 감쌈

    if START in existing and END in existing:
        # 기존 블록 교체 (replace_or_append)
        new_text = _replace_or_append(existing, wrapped)
    else:
        # 파일 끝에 추가
        new_text = existing + "\n\n" + wrapped

    claude_md_path.write_text(new_text)

Adapters — 새 AI 도구 지원 추가

새로운 AI 도구(예: Cursor, Windsurf)를 지원하려면 3줄의 서브클래스만 작성하면 됩니다.

# adapters/claude_code.py
from .base import BaseAdapter

class ClaudeCodeAdapter(BaseAdapter):
    instruction_filename = "CLAUDE.md"

# 새 도구 추가 예시
class CursorAdapter(BaseAdapter):
    instruction_filename = ".cursorrules"

테스트 전략

agent-harness는 실제 파일시스템 효과를 검증하는 통합 테스트 방식을 씁니다. Mock 없이 임시 디렉터리를 만들어서 실제로 설치하고 결과를 확인합니다.

# 테스트 예시
def test_install_creates_agents_directory(tmp_path):
    store = Store(test_store_root)
    items = [store.resolve("rule:workflow/plan-first")]

    result = install(items, project_path=tmp_path, tool_id="claude-code")

    assert (tmp_path / ".agents" / "rules" / "workflow" / "plan-first.md").exists()
    assert (tmp_path / ".agents" / "manifest.json").exists()
    assert "AGENT-HARNESS_START" in (tmp_path / "CLAUDE.md").read_text()