AI 코딩 에이전트를 위한 안전하고 구체적인 운영 계약으로 레포지토리를 전환하는 방법

HarnessME는 기존에 존재하는 레포지토리의 구조와 컨벤션을 읽어 들인 다음, 유지 관리되는 AGENTS.md, 범위가 지정된 모듈 가이드(scoped module guides), 그리고 에이전트별 통합 기능을 생성합니다. 이 도구는 에이전트에게 어디를 변경해야 하는지, 무엇이 진실로 남아 있어야 하는지, 작업의 유효성을 어떻게 검증할 수 있는지, 그리고 핵심 영역을 건드리기 전에 개발자에게 언제 문의해야 하는지를 알려줍니다.

일반적인 지침은 에이전트가 추측하게 만듭니다. HarnessME는 레포지토리를 가독성 있게 만듭니다: 실제 파일과 유효성 검사 명령에 근거하여 안내를 제공하고, 결합된 변경 사항을 강조하며, 문서화 드리프트(documentation drift)를 감지하고, 명시적인 인간의 게이트(human gate)로 고위험 경로를 보호합니다. 이는 로컬에서 스크립트 가능한 CLI이며, 호스팅 서비스나 HarnessME 계정이 필요하지 않습니다.

Windows, macOS 또는 Linux 환경에서 Node.js 26.4 이상이 필요합니다.

npm install -g harnessme
cd your-repository
harnessme

harnessme는 인터랙티브 대시보드를 열어줍니다. Harness가 없는 레포지토리의 경우, Initialize를 선택하면 아무것도 쓰기 전에 제공자(provider), 모델(model), 사고 수준(thinking level), 검토 깊이(review depth), 그리고 선택적 프로젝트 컨텍스트에 대한 안내를 받게 됩니다.

대시보드: 생성된 문서 탭을 통한 레포지토리 제어, 안내 기반 설정, 실시간 운영 진행 상황, 품질 인텔리전스, 중요 게이트 관리.

레포지토리 루트에서 언제든지 harnessme를 실행하세요. 이 대시보드는 기본 인터페이스이며 전체 라이프사이클을 한곳에 보관합니다:

대시보드(Dashboard) — Harness 상태, 제공자/모델 설정, 안전 게이트 카운트, 그리고 생성된 모든 Harness 문서를 검사할 수 있습니다. [ / ]를 사용하세요.

또는 Tab 키를 눌러 루트 계약(root contract), 범위 지정 가이드(scoped guides), 에이전트 팩(agent pack), 핵심 정책(critical policy), 그리고 중첩 모듈 계약(nested module contracts)으로 전환할 수 있습니다. 가이드 설정(Guided configuration)— 제공업체, 모델, Codex 사고 수준, 검토 깊이, 그리고 선택적 컨텍스트를 기억나지 않는 플래그 없이 선택합니다. 작동 진행 상황(Operation progress)— 분석, AI 검토, 작성된 가이드, 통합 단계를 실시간으로 따릅니다. 품질 지능, 기록 및 복구(Quality intelligence, history, and remediation)— 증거, 탐색, 작업, 문서화, 거버넌스를 비교합니다. 초기화, 새로고침, 수정 전반에 걸친 점수 추세를 검사한 다음, 실패한 체크 중 아무거나 선택하여 복구 가능한 지점, 예상 점수, 권장 워크플로우 및 검증된 결과를 확인합니다. 핵심 게이트 관리자(Critical Gate Manager)— 민감한 경로에 대해 명시적인 개발자 확인 게이트를 활성화, 해제, 제거 또는 추가합니다. 해제된 제안은 새로고침 후에도 계속 해제 상태로 유지됩니다. 지식 그래프(Knowledge Graph)— 터미널 안에 머무르면서 G 키를 눌러 구조화된 보기와 힘 기반 보기 사이를 전환하거나, 두 노드에 P 키를 눌러 그들 간의 관계 경로를 설명하게 할 수 있습니다. 생성 안전성(Generation safety)— 격리된 작업 공간에서 생성된 문서 차이점(diffs)을 미리 보고, 소스 코드나 유지 관리자 사실을 롤백하지 않고 최신 로컬 스냅샷 20개 중 하나를 복원합니다.

스크립팅, CI 실행, 또는 필요한 작업을 이미 알고 있을 때는 명령어를 사용하세요:

harnessme init # harness를 비대화형으로 생성하거나 프롬프트와 함께 생성
harnessme init --targets codex,pr-agent # 선택된 형식과 PR-Agent의 .pr_agent.toml을 생성
harnessme refresh # 리포지토리 변경 후 업데이트
...

전체 명령어 및 핵심 변경 워크플로우 참조는 이 README의 더 아래쪽에 있습니다.

• 유지 관리자 규칙과 활성 보호 경로를 표시하고 모든 작업에서 표준 에이전트 계약을 로드하는 간결한 루트 AGENTS.md. 에이전트는 자신의 변경 사항에 관련 있는 참조만 열어보고, 주변 소스 및 테스트를 검사합니다. - 표준적인 .harnessme/agent-pack/agent.md

이는 에이전트를 작업 관련 참조로 라우팅하고, 보호된 경계를 명명하며, 최대 다섯 개의 소스 기반 불변량(invariant)을 노출합니다. 상세하게 생성된 운영 계약은 .harnessme/agent-pack/contract.md에 존재합니다.

; 가져온 유지 관리 규칙은 루트 파일에 남아 있습니다. - 범위가 지정된 참조를 연결하는 짧고 중첩된 모듈 가이드입니다. 에이전트는 로컬 탐색을 통해 소유자, 의존성 또는 테스트를 확립하지 못할 때 harnessme context <경로>를 사용합니다. .harnessme/CRITICAL.md

, 그 기계가 판독 가능한 동반 파일인 .harnessme/critical.json, 롤백 가이드 및 핵심, 보안, 영속성(persistence), 청구(billing), 배포(deployment), 그리고 공개 계약 변경에 대한 강제 실행 게이트를 포함합니다. - 기본 확인 규칙은 시작업(startup), 오케스트레이션(orchestration), 모델 및 프롬프트 팩토리, 도구 등록, 요청 처리, 영속 상태, 및 공개 이벤트 매핑을 포함한 기반 진입 방법과 핵심 인프라 계약에 적용됩니다. 새롭게 식별된 경계는 편집 전에 활성 게이트를 받습니다.

• Codex, Claude Code, Claude Desktop, Cursor, PR-Agent 및 기타 선택된 에이전트 형식의 제공자 파일입니다.
• 다섯 가지 가중치 차원(증거 폭, 의미론적 파일 커버리지, 주요 핵심 경로에 대한 컨텍스트 전달 커버리지, 의존성 밀도, 테스트 연결, 인용되고 실행 가능한 가이드 깊이, 생성된 링크 무결성, 평가 신뢰도, 역사적 추세, 순위가 매겨진 발견 사항 및 실행 가능한 개선 계획)을 가진 중요한 대시보드와 harnessme quality 점수표입니다. 초기화만으로는 100점을 얻을 수 없으며, 해결되지 않은 핵심 경로 제안은 점수를 '우수(excellent)' 이하로 제한합니다. - 버전 관리되는 .harnessme/knowledge-graph.json, 에이전트용 기능 지도, 그리고 구조적이고 힘 기반(force-directed) 뷰를 가진 터미널 탐색기가 있습니다. - 기존의 구성, 배포 및 문서화 경로는 AI가 검토한 기능 범위를 근거지을 수 있으며, 인용되고 경계 지어진 대표 경로만이 생성된 그래프에 진입합니다.

HarnessME는 Windows, macOS 또는 Linux에서 Node.js 26.4 이상을 요구합니다. 대시보드는 OpenTUI가 필요로 하는 Node의 실험적 FFI 플래그를 자동으로 활성화합니다. 설치 후에는 분석하려는 레포지토리에서 모든 명령어를 harnessme … 형태로 직접 실행하십시오.

모델 지원 생성을 위해 최소한 하나의 지원되는 프레임워크 CLI(Codex, Claude Code 또는 Cursor)를 설치하고 로그인해야 합니다. 모델 추론 없이 완전히 로컬로 실행하려면 --deterministic 플래그를 사용하십시오.

HarnessME는 추론 전에 선택된 CLI의 로그인 상태를 확인합니다. harnessme providers doctor --provider cursor를 실행하여 설치, 로그인 및 모델 검색을 확인하고, --probe를 추가하여 실제 구조화된 출력 호출을 수행하고 응답 시간을 측정할 수 있습니다. 프로브는 --model로 모델 오버라이드를 사용할 수 있습니다. cursor-agent 명령어와 Cursor의 agent 명령어가 모두 지원되며, 이름이 다른 agent 프로그램은 무시됩니다. Cursor는 그 외에는 성공적인 JSON 프로세스 결과 내부에 오류를 반환할 수 있으며, HarnessME는 해당 오류를 직접 보고합니다. 초기화 및 새로고침은 이제 프롬프트나 응답을 출력하지 않으면서 각 모델 단계, 완료 시간 및 30초마다 여전히 실행 중인 신호를 보고합니다. Cursor 지원 초기화는 여러 모델 호출을 수행하며 단계별로 몇 분이 걸릴 수 있습니다. 느리거나 모델 특정 동작의 경우, --model과 사용 가능한 모델 ID를 전달하거나 --council-size 1을 사용하여 검토 호출 횟수를 줄일 수 있습니다.

HarnessME가 하네스를 생성하고 검토하는 방법

harnessme init이 실행되면 다음 작업을 수행합니다:

• 번들된 구문 트리 문법으로 지원되는 소스 파일을 스캔하고, 레포지토리 구성 및 문서(.agents/ 아래의 중첩된 유지 관리자 가이드 포함)를 읽습니다.

• 패키지 메타데이터, 포매터 및 린터 설정, 타입 구성, 기여 문서, 그리고 Git 히스토리를 읽습니다.
• 프로젝트 목적, 레포지토리 구조, 코딩 컨벤션, 도메인 불변량(domain invariants), 모듈 소유권, 검증 명령어, 임포트 허브, 자주 변경되는 파일, 그리고 구현과 더 이상 일치하지 않는 문서 참조를 감지합니다.
• 이러한 발견 사항들을 .harnessme/facts/에 저장합니다.

• 추론된 모든 컨벤션은 레포지토리를 기준으로 한 파일 및 라인 인용을 포함하며; 로컬 임포트는 그래프 증거를 위해 원본 라인을 유지합니다. 소스 및 발견된 문서의 해시 값은 harnessme check가 파일 목록이 동일하더라도 콘텐츠 변경을 감지할 수 있게 합니다.
• 결정론적(deterministic) AGENTS.md 기준선과 가능한 중요 파일 및 모듈의 제한된 목록을 구축합니다. 결정론적 인용은 검사할 소스를 식별하며, 이는 검증된 행동 불변량으로 제시되지 않습니다.
• AI가 활성화되었을 때 네 단계 모델 파이프라인을 사용합니다: 증거 추출(evidence extraction), 독립적인 주장 검증(independent claim verification), 하네스/참조 저작권(harness/reference authorship), 그리고 최종 기준선 비교입니다. 작성자와 검토자는 동일한 제한적이고 수정된 레포지토리 컨텍스트를 받으며; 이는 절대 저장되지 않습니다. 검토 위원회는 모든 후보를 검증하고 구체적인 경로, 심볼, 인용, 워크플로우 및 범위 지정 커버리지를 기반으로 가장 강력한 유효 결과를 선택합니다. 로컬 검증이 모든 후보를 거부할 때만 집중적인 수정 패스(focused repair pass)가 실행됩니다.
• 간결하고 레포지토리별 루트 AGENTS.md, 검토된 의미론적 기능 정의(semantic feature definitions), 아키텍처 라우팅과 중요 변경 감사 표준을 갖춘 전용 에이전트 팩, 그리고 관심사 중심의 실행 가능한 변경 매뉴얼을 작성합니다. 각 범위 지정 가이드는 책임, 지원되는 확장 심(extension seams), 불변량, 결합된 변경 영향(coupled change impact), 안티패턴, 워크플로우, 검증 및 유지보수 트리거를 식별합니다. HarnessME는 그런 다음 상세한 중첩 AGENTS.md를 배치합니다.

적용 가능한 모듈 디렉터리 내의 운영 계약(operating contracts)을 통해 관리합니다. 교차 영역 가이드(Cross-cutting guides)는 여러 구체적인 범위(concrete scopes)를 다룰 수 있습니다. 사용되지 않는 관리 모듈 가이드는 새로고침 시 제거됩니다. - Builds
.harnessme/knowledge-graph.json
,
.harnessme/FEATURES.md
,
그리고 초점 기능 가이드(focused feature guides)를 통해 관리합니다. 결정론적 실행(Deterministic runs)은 모듈, 파일, 테스트, 임포트, 문서화 및 중요 경로를 매핑하며, 유지보자 가이드에서 인용하는 정확한 소스 파일에 대한 링크를 포함합니다. harnessme context는 이러한 링크를 사용하여 변경된 파일과 관련된 가이드를 표시(surface)합니다. 검토된 AI 실행은 증거 기반의 기능적 의미를 추가합니다. 유지보자가 재정의하는 내용은 항상 우선권을 갖습니다. 새로고침 시 검토된 활성 게이트(active gates)는 유지됩니다. 만약 모델 초안이 특정 기능을 누락하더라도, 새로고침은 기존 가이드를 유지하고 해당 범위 내의 소스 파일 및 인용된 증거는 변경되지 않습니다. - 제안된 게이트를 보안(security), 영속성(persistence), 공개 계약(public-contract), 청구(billing), 배포(deployment), 공유 코어(shared-core) 또는 기타로 분류합니다. 테스트 파일은 자동 게이트 지명에서 제외됩니다. 명시적으로 이름 붙여진 Python 메서드를 보호하는 임포트된 유지보자 규칙은 해당 정의가 하나의 소스 파일로 해결될 때만 활성 파일 게이트가 되며, 모호한 이름은 보존된 지침(preserved directive)에 남아 있습니다. 다른 후보들은 검토될 때까지 제안 상태를 유지합니다.

• 결과적인 하네스(harness)를 목적, 문서화, 검증, 증거, 운영 규칙, 핵심 경계, 워크플로우, 기능 탐색, 범위 지정된 참조 및 문서화 일관성 측면에서 점수화합니다.
• 로컬에서 안전 언어와 관리 자리 표시자(managed placeholders)를 강제하고, 그 결과를 선택된 모든 프레임워크에 배포하며,
  .harnessme/CRITICAL.md
  ,
  .harnessme/critical.json
  ,
  CODEOWNERS,
  선택 시 Claude Code 훅(hook), Lefthook 구성 및 GitHub Actions 워크플로우를 생성합니다.

기존의 관리되지 않은 AGENTS.md 지침은 폐기되는 대신 프로젝트 지침으로 보존됩니다. 임포트된 루트 계약은 .harnessme/imported-AGENTS.md에 아카이브되며, 관리되지 않은 중첩 계약(unmanaged nested contracts)은 제자리에 남아 있습니다. 애플리케이션 소스 파일은 분석되지만 재작성되지는 않습니다.

Model-assisted generation은 Codex, Claude Code 또는 Cursor의 인증을 재사용합니다. --provider를 사용하여 런타임을 선택하세요.

; auto

설치된 지원되는 CLI 중 첫 번째 것을 해석합니다:

harnessme init --provider auto

--model 없이 터미널에서 실행할 때, HarnessME는 제공자를 해석한 후 모델을 선택하도록 요청합니다. Codex와 Cursor는 사용 가능한 모델 카탈로그를 노출하며, 모델 열거가 불가능한 제공자는 구성된 기본값 또는 수동으로 입력한 모델 ID를 제공합니다. Codex는 또한 네이티브 추론 노력 설정에 매핑되는 Fast, Balanced, 및 Deep 사고 레벨을 제공합니다. 스크립트와 CI의 경우, --thinking-level low|medium|high로 해당 선택을 명시적으로 설정하세요 (Codex 전용):

harnessme init --provider codex --model your-model --thinking-level high

지원되는 추론 런타임은 codex, claude-code, 및 cursor입니다. HarnessME는 이들을 비대화형으로 격리된 임시 디렉토리에서 실행하며, 이 디렉토리에는 리포지토리 자체가 아닌 경계가 지정되고 수정된 분석 입력만 포함됩니다. 입력 선택은 루트 README, architecture/policy 문서, 매니페스트 및 각 모듈의 핵심 소스에 대한 균형 잡힌 샘플을 우선합니다. 모델은 먼저 결정론적 발견 사항을 구조화되고 증거 인용된 사실로 풍부하게 만듭니다. 그런 다음 전체 AGENTS.md를 작성합니다.