repository-harness

어떤 소프트웨어 저장소(repo)든 에이전트가 즉시 사용할 수 있는 워크스페이스로 변환하세요.

repository-harness는

Claude Code, Codex, Cursor 및 기타 코딩 에이전트를 위한 저장소 수준의 운영 하네스 (operating harness)입니다. 이 도구는 에이전트가 코드를 수정하기 전에 필요로 하는, 누락된 프로젝트 컨텍스트 (context)를 제공합니다: 어디서 시작해야 하는지, 제품 계약 (product contract)이 무엇을 말하는지, 작업의 위험도는 어느 정도인지, 어떤 증명이 필요한지, 그리고 미래의 에이전트가 상속받아야 할 결정은 무엇인지 등을 알려줍니다.

앱(App)은 사용자가 접하는 것이고, 하네스(Harness)는 에이전트가 접하는 것입니다.

AI 지원 소프트웨어 개발을 더 신뢰할 수 있고, 검사 가능하며, 인간이 조종하기 더 쉽게 만드는 실용적이고 재사용 가능한 패턴을 원하신다면 이 저장소에 Star를 눌러주세요.

이 프로젝트는 다음과 같은 간단한 아이디어를 탐구합니다:

코딩 에이전트에게 필요한 것은 더 나은 프롬프트 (prompt)만이 아닙니다. 그들에게는 더 나은 저장소 (repository)가 필요합니다.

대부분의 저장소는 익숙한 코드베이스에서 코드를 읽는 인간을 위해 구축되었습니다. 코딩 에이전트는 보통 채팅 프롬프트와 파일의 얕은 스냅샷 (snapshot)만 가지고 진입합니다. 이는 다음과 같은 흔한 실패 모드로 이어집니다:

• 에이전트가 제품의 의도를 이해하기 전에 코드를 수정함.
• 중요한 제약 조건이 채팅 기록이나 누군가의 머릿속에만 존재함.
• 검증 기대치가 모호하거나 너무 늦게 발견됨.
• 아키텍처 (architecture) 트레이드오프 (tradeoffs)가 상속되는 대신 반복됨.
• 대규모 요청이 검토 가능한 스토리 크기의 작업으로 분할되지 않음.

저장소가 채팅 기록에만 의존하지 않고 에이전트가 실질적인 엔지니어링 질문에 답할 수 있도록 도와줄 때, 비로소 저장소에 하네스가 생기기 시작합니다:

• 무엇을 먼저 읽어야 하는가?
• 이것은 어떤 유형의 작업인가?
• 어떤 제품 계약에 영향을 미치는가?
• 변경 사항의 위험도는 어느 정도인가?
• 작업이 완료되었음을 보여줄 증명은 무엇인가?
• 미래의 에이전트가 상속받아야 할 결정이나 교훈은 무엇인가?

이 저장소에서 이러한 답변은 다음 파일들에 담겨 있습니다:

AGENTS.md
— 로컬 프로젝트 노트와 Harness 문서 링크가 포함된 안정적인 에이전트 심 (agent shim).

docs/HARNESS.md
— 인간-에이전트 협업 모델.

docs/FEATURE_INTAKE.md
— 소규모, 일반, 고위험 작업 분류.

docs/ARCHITECTURE.md
— 아키텍처 발견 및 경계 규칙.

docs/TEST_MATRIX.md

— behavior-to-proof validation expectations (행동-증명 검증 기대치).

docs/stories/

— story packets (스토리 패킷) 및 backlog items (백로그 항목).

docs/decisions/

— durable decisions (지속 가능한 결정) 및 tradeoffs (트레이드오프).

docs/templates/

— 재사용 가능한 spec (명세), story (스토리), decision (결정) 및 validation (검증) 템플릿.

OpenAI는 이러한 변화를 인간이 조종(steer)하고 에이전트가 실행(execute)하는 agent-first (에이전트 우선) 세상이라고 설명합니다:

대상 프로젝트 디렉토리에서 다음을 실행하세요:

curl -fsSL "https://raw.githubusercontent.com/hoangnb24/repository-harness/main/scripts/install-harness.sh?$(date +%s)" | bash -s -- --yes

Windows PowerShell에서는 다음을 실행하세요:

& ([scriptblock]::Create((irm "https://raw.githubusercontent.com/hoangnb24/repository-harness/main/scripts/install-harness.ps1"))) -Yes

대상에 이미 AGENTS.md, docs/ 또는 scripts/가 있는 경우, 다음 중 하나를 선택하세요:

# 기존 파일을 이동하지 않고 기존 Harness 저장소를 업데이트
curl -fsSL "https://raw.githubusercontent.com/hoangnb24/repository-harness/main/scripts/install-harness.sh?$(date +%s)" | bash -s -- --merge --yes
# AGENTS.md, docs/, scripts/를 백업하고 교체
...

# 기존 파일을 이동하지 않고 기존 Harness 저장소를 업데이트
& ([scriptblock]::Create((irm "https://raw.githubusercontent.com/hoangnb24/repository-harness/main/scripts/install-harness.ps1"))) -Merge -Yes
# AGENTS.md, docs/, scripts/를 백업하고 교체
...

프로젝트에 이미 Harness가 있고, 기존의 AGENTS.md, docs/ 또는 scripts/ 경로를 백업으로 이동시키지 않고 새로 추가된 Harness 파일만 추가하고 싶을 때는 --merge를 사용하세요. 기존 파일은 건드리지 않으며, 누락된 Harness 파일만 생성됩니다.

AGENTS.md에 여전히 전체 생성된 운영 가이드가 포함되어 있는 이전 버전의 Harness 설치의 경우, 이를 작고 안정적인 shim (심)으로 새로고침하세요:

curl -fsSL "https://raw.githubusercontent.com/hoangnb24/repository-harness/main/scripts/install-harness.sh?$(date +%s)" | bash -s -- --merge --refresh-agent-shim --yes

새로고침 (refresh) 시 기존 파일을 백업합니다. 만약 기존에 Harness가 생성한 가이드가 감지되면, 이를 shim으로 교체합니다. 만약 파일이 사용자 정의(custom)된 것으로 판단되면, 프로젝트의 로컬 지침을 덮어쓰는 대신 표시된 Harness 블록을 추가하거나 업데이트합니다.

프로젝트가 Claude Code로 구동되는 경우, --claude를 추가하세요.

Claude Code는 AGENTS.md를 자동으로 로드하지 않으므로, 이 옵션이 없으면 설치된 harness가 새로운 세션(fresh sessions)에서 보이지 않습니다. 이 플래그를 사용하면 CLAUDE.md를 설치(또는 새로고침)하며, 이 파일 내의 표시된 Harness 블록 @이 AGENTS.md와 docs/FEATURE_INTAKE.md를 모든 세션의 컨텍스트 (context)로 가져오도록 (import) 합니다. 기존의 CLAUDE.md가 있다면 백업 후 해당 블록이 추가됩니다. 플래그 없는 일반 설치는 CLAUDE.md를 절대 건드리지 않습니다:

curl -fsSL "https://raw.githubusercontent.com/hoangnb24/repository-harness/main/scripts/install-harness.sh?$(date +%s)" | bash -s -- --claude --yes

또는 특정 경로에 설치하려면:

curl -fsSL "https://raw.githubusercontent.com/hoangnb24/repository-harness/main/scripts/install-harness.sh?$(date +%s)" | bash -s -- --directory /path/to/project --yes

& ([scriptblock]::Create((irm "https://raw.githubusercontent.com/hoangnb24/repository-harness/main/scripts/install-harness.ps1"))) -Directory C:\path\to\project -Yes

파일을 작성하기 전에 변경 사항을 미리 확인하려면 Bash에서는 --dry-run을, PowerShell에서는 -DryRun을 사용하세요.

설치 프로그램은 또한 현재 플랫폼에 맞는 사전 빌드된 Harness CLI를 다운로드하고, .sha256 체크섬 (checksum)을 검증한 뒤, macOS/Linux의 경우 scripts/bin/harness-cli에, Windows의 경우 scripts/bin/harness-cli.exe에 설치합니다. Rust CLI는 주요 Harness 도구이자 안정적인 명령 경로입니다.

Harness CLI 릴리스 자산 (release assets)은 Harness CLI Release GitHub Actions 워크플로 (workflow)를 통해 태그 (tags)로부터 게시됩니다. 설치 프로그램은 각 릴리스에 macOS arm64, macOS x64, Linux x64, Linux arm64, 그리고 Windows x64용 harness-cli-<platform> 및 harness-cli-<platform>.sha256 자산이 포함되어 있을 것으로 예상합니다. Windows 자산은 harness-cli-windows-x64.exe입니다.

plus harness-cli-windows-x64.exe.sha256

.

병합된 풀 리퀘스트 (Merged pull requests)는 Post-Merge Maintenance 워크플로 (workflow)에 의해 CHANGELOG.md에 기록됩니다.

병합된 PR이 Rust CLI 소스, 스키마 (schema), Cargo 메타데이터 (metadata), 또는 CLI 릴리스 패키징 (release packaging)을 변경하면, 해당 워크플로가 CLI 패치 버전 (patch version)을 올리고, scripts/harness-cli-release-tag를 업데이트하며, harness-cli-v* 태그를 생성하고, 해당 태그에 대한 Harness CLI 릴리스 빌드를 실행합니다.

하네스 (harness)를 이해하는 가장 빠른 방법은 작은 데모를 살펴보는 것입니다:

docs/demo/README.md

: 간단한 제품 아이디어가 구현이 시작되기 전에 어떻게 제품 문서 (product docs), 스토리 (stories), 검증 기대치 (validation expectations), 그리고 결정 사항 (decisions)이 되는지를 보여줍니다.

전형적인 흐름은 다음과 같습니다:

인간의 의도 (human intent) 또는 제품 사양 (product spec)
-> 제품 계약 (product contract)
-> 기능 수렴 (feature intake)
...

구현 프롬프트 (Implementation prompts)는 코드에 바로 전달되지 않습니다. 이들은 먼저 기능 수렴 (feature intake) 단계를 거치고, 필요할 때 스토리 크기의 작업 (story-sized work)이 되며, 제품 검증 (product validation)과 하네스 유지보수 (harness maintenance) 기대치를 모두 담게 됩니다.

하네스는 특정 도구에 의존하지 않고도 선택적인 외부 도구 (린터 (linters), 코드 그래프 서버 (code-graph servers), 배포 체크 (deploy checks))를 사용할 수 있습니다. 도구를 특정 *기능 (capability)*의 제공자 (provider)로 등록하면, 하네스는 해당 도구가 실제로 존재하는지 스캔하며, 워크플로 단계 (workflow step)는 갖춰진 도구를 사용합니다. 도구가 없으면 깔끔하게 건너뛸 뿐, 결코 실패로 이어지지 않습니다.

# 도구를 특정 기능의 제공자로 등록
scripts/bin/harness-cli tool register --name deploy-check --kind cli \
--capability deploy-verification --command ./scripts/deploy-check.sh \
...

종류 (Kinds: cli, binary, mcp, skill, http)는 이를 에이전트 범용적 (agent-generic)으로 만듭니다. 각 에이전트 런타임 (agent runtime)은 자신이 오케스트레이션 (orchestrate)할 수 있는 것을 사용합니다. 전체 모델, 성능 저하 계층 (degrade ladder), 그리고 도구를 흐름 단계 (flow step)에 연결하는 방법은 docs/TOOL_REGISTRY.md를 참조하세요.

이 리포지토리 (repository)는 Harness v0에 있습니다.

아직 애플리케이션 구현체나 내장된 제품 사양 (product specification)은 존재하지 않습니다. 현재 작업은 재사용 가능한 프로젝트 하네스 (project harness)를 구축하는 것입니다. 즉, 파일 구조, 에이전트 운영 모델 (agent operating model), 기능 수용 프로세스 (feature intake process), 스토리 템플릿 (story templates), 그리고 인간과 에이전트가 향후 사용자가 제공할 사양을 구현 작업으로 전환할 수 있도록 돕는 검증 기대치 (validation expectations)를 만드는 단계입니다.

현재 정의된 제품 계약 (product contract)은 없습니다.

사용자가 프로젝트 사양 (project specification)을 제공하면, 이를 첫 번째 빌드아웃 (buildout)을 위한 입력 사양으로 추가하거나 참조하십시오. 그 후, 사양으로부터 다음과 같은 작은 실행형 아티팩트 (living artifacts)들을 도출합니다:

docs/product/
: 사양으로부터 생성된 현재의 제품 계약 (product contract) 파일들.

docs/stories/
: 선택된 작업으로부터 생성된 스토리 패킷 (story packets) 및 백로그 (backlog).

docs/TEST_MATRIX.md
: 동작-증명 제어 패널 (behavior-to-proof control panel).

docs/decisions/
: 지속적인 결정 사항 (durable decisions) 및 트레이드오프 (tradeoffs).

실제 프로젝트에서 사양이나 제품 상세 분석 (product breakdown)을 제공하기 전까지는, 이 하네스 (harness) 내에 프로젝트별 사양을 보관하지 마십시오.

project/
AGENTS.md
README.md
...

이 프로젝트는 초기 단계이며, 실제 에이전트 실패 사례, 하네스 설치 예시, 문서 개선, 그리고 재사용 가능한 워크플로우 패턴 (workflow patterns)으로부터 가장 큰 도움을 받습니다.
기여 아이디어는 CONTRIBUTING.md를 참조하세요.

유용한 기여 사례는 다음과 같습니다:

• 실제 프로젝트에서 하네스가 어떻게 작동하는지 보여주기.
• 누락된 템플릿을 추가하거나 기존 템플릿 개선하기.
• 다양한 스택 (stacks)에 대한 검증 패턴 (validation patterns) 제안하기.
• 리포지토리에 컨텍스트 (context)가 부족하여 에이전트가 잘못된 변경을 수행한 실패 사례 공유하기.
• Claude Code, Codex, Cursor 및 기타 도구 간의 하네스 동작 비교하기.

이 아이디어가 공감된다면, 리포지토리에 스타 (star)를 눌러주시고 코딩 에이전트 (coding agents)를 활용해 개발 중인 분들에게 공유해 주세요.

짧은 설명:

Claude Code, Codex, Cursor 및 기타 코딩 에이전트를 위한 에이전트 준비 완료 리포지토리 하네스 (agent-ready repo harness): AGENTS.md, 제품 계약 (product contracts), 스토리 패킷 (story packets), 검증 매트릭스 (validation matrix) 및 결정 기록 (decision records) 포함.