{"id":50499217,"url":"https://github.com/parkjangwon/make-harness","last_synced_at":"2026-06-02T10:01:42.929Z","repository":{"id":352041776,"uuid":"1213596357","full_name":"parkjangwon/make-harness","owner":"parkjangwon","description":"A calm project-local AI harness starter for durable project contracts.","archived":false,"fork":false,"pushed_at":"2026-04-17T15:27:37.000Z","size":37,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-17T17:16:19.128Z","etag":null,"topics":["agent-skill","ai-harness","claude-code","codex","gemini-cli","project-contract","skills-sh"],"latest_commit_sha":null,"homepage":"https://github.com/parkjangwon/make-harness","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/parkjangwon.png","metadata":{"files":{"readme":"README.ko.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-17T14:50:59.000Z","updated_at":"2026-04-17T15:27:40.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/parkjangwon/make-harness","commit_stats":null,"previous_names":["parkjangwon/make-harness"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/parkjangwon/make-harness","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parkjangwon%2Fmake-harness","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parkjangwon%2Fmake-harness/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parkjangwon%2Fmake-harness/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parkjangwon%2Fmake-harness/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/parkjangwon","download_url":"https://codeload.github.com/parkjangwon/make-harness/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parkjangwon%2Fmake-harness/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33816488,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-02T02:00:07.132Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-skill","ai-harness","claude-code","codex","gemini-cli","project-contract","skills-sh"],"created_at":"2026-06-02T10:01:39.797Z","updated_at":"2026-06-02T10:01:42.923Z","avatar_url":"https://github.com/parkjangwon.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# make-harness\n\n`make-harness`는 각 저장소에 프로젝트 로컬 하네스를 설치하고 유지하는 도구다.\n\n하나의 canonical durable contract에 저장소별 규칙, 명령, 제약, guardrail을 모으고, 그 계약에서 `AGENTS.md`, `CLAUDE.md`, `GEMINI.md` 같은 thin projection을 다시 만들고, 하네스가 healthy한지 점검한다.\n\n`make-harness`는 개발론 프레임워크가 아니고, 실행 프레임워크도 아니며, orchestration 레이어도 아니다. 더 강한 workflow/methodology 레이어와 조합되는 framework-agnostic local rule layer로 남는 것이 목적이다.\n\n영문 버전: [README.md](README.md)\n\n## 왜 설치하나\n\n`make-harness`를 쓰기 전 흔한 고통:\n\n### Before\n\n- `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`가 조금씩 달라진다\n- 새 AI 세션마다 같은 프로젝트 규칙을 다시 설명한다\n- 어느 파일이 진짜 기준인지 애매해진다\n- 위험한 변경 기준이 문서보다 사람 기억에 의존한다\n\n### After\n\n- durable contract 하나가 기준이 된다\n- thin entry 파일은 손으로 맞추는 대신 다시 생성한다\n- audit / completion check가 하네스가 실제로 healthy한지 말해준다\n- 더 큰 에이전트 런타임을 들이지 않고도 repo-local 기본값이 세션을 넘어 유지된다\n\n처음 체감되는 효용은 단순하다. 같은 설명을 덜 반복하고, drift 난 루트 파일이 줄어든다.\n\n## 이런 사람에게 맞다\n\n`make-harness`는 이런 개발자와 팀에 맞습니다.\n\n- 한 리포에서 둘 이상의 AI 코딩 도구를 같이 쓴다\n- 새 AI 세션이 열릴 때마다 프로젝트 규칙, 명령, 가드레일을 다시 설명하게 된다\n- 여러 루트 instruction 파일을 손으로 맞추기보다 repo-local source of truth 하나를 두고 싶다\n\n예를 들면 Claude Code, Codex, Gemini CLI, Cursor 같은 도구를 함께 쓰는 팀이 대표적인 사용자입니다.\n\n## 특히 잘 맞는 환경\n\n`make-harness`는 프로젝트마다 저장소 로컬 규칙이 다른 환경에서 특히 유용합니다.\n\n대표적으로 잘 맞는 환경:\n\n- 고객사/프로덕트별로 리포를 많이 운영하는 솔루션/서비스 개발 회사\n- 레거시 리포, 신규 리포, 보안 민감 리포가 함께 섞여 있는 팀\n- 여러 개발자나 여러 AI 도구가 같은 리포를 시간차를 두고 계속 건드리는 조직\n- 승인 규칙, 기본 검증 명령, 민감 경로가 프로젝트마다 다른 경우\n- 반복 설명과 루트 파일 drift가 장기적으로 계속 쌓이는 리포\n\n상대적으로 덜 맞는 환경:\n\n- 금방 버릴 일회성 리포\n- 아주 짧게 쓰고 버릴 실험용 PoC\n- 아직 durable한 로컬 규칙을 유지할 필요가 거의 없는 리포\n\n## 더 강한 워크플로와의 조합\n\n`make-harness`는 더 강한 workflow 시스템을 대체하려는 도구가 아니라, 그 아래에서 함께 조합되도록 설계되어 있습니다.\n\n좋은 조합은 보통 이렇게 나뉩니다.\n\n- `make-harness`는 저장소 로컬 계약을 맡는다: 기본값, 명령, 제약, 승인 규칙, thin projection sync\n- ecc, superpowers 같은 상위 워크플로 도구는 planning, TDD, code review loop, sub-agent coordination 같은 실행 레이어를 맡는다\n- 결과적으로 위 레이어는 어떻게 일할지를 담당하고, `make-harness`는 각 저장소의 로컬 규칙을 안정적으로 유지한다\n\n이 방식이 모든 리포에 하나의 전역 workflow를 억지로 강제하는 것보다 보통 더 현실적입니다.\n\n실제 멀티 에이전트 흐름으로 풀면 보통 이런 역할 분리가 잘 맞습니다.\n\n- planner가 작업을 나누고 실행 방향을 정한다\n- generator 또는 executor가 코드, UI, 마이그레이션 같은 실제 산출물을 만든다\n- independent evaluator 또는 reviewer가 self-evaluation에만 기대지 않고 명시적인 품질 기준으로 결과물을 검토한다\n- `make-harness`는 이들이 함께 읽는 저장소 로컬 계약을 맡는다: definition of done, verification command, approval boundary, constraint, 간단한 rubric 힌트\n\n중요한 점은 마지막 줄입니다. `make-harness`는 품질 기대치와 로컬 규칙을 보존하지만, planner / generator / evaluator 루프 자체를 스케줄링하는 실행 엔진이 되지는 않습니다.\n\n## 독립 evaluator를 붙이기 좋은 구조\n\n`make-harness`는 결과물을 만든 에이전트가 자기 결과를 혼자만 평가하는 구조보다, 독립 reviewer/evaluator가 따로 검증하는 구조가 더 안정적이라고 봅니다.\n\n그래서 durable contract에는 아래 같은 것을 담기 좋습니다.\n\n- 명시적인 `definition_of_done`\n- 기본 `verification_policy`\n- test / lint / typecheck / e2e / visual review용 `project_commands`\n- 이 저장소에서 무엇을 좋다고 볼지 알려주는 짧은 rubric 힌트\n\n반대로 아래 같은 것은 durable contract에 넣을 일이 아닙니다.\n\n- review loop를 몇 번 돌릴지\n- 어떤 orchestration framework가 루프를 스케줄할지\n- planner / generator / evaluator의 고정 토폴로지\n\n## `/make-harness`를 실행하면 무슨 일이 일어나나\n\n전형적인 흐름은 이렇습니다.\n\n```text\nYou: /make-harness\n\nAgent:\n1. 저장소와 기존 harness 파일을 먼저 본다\n2. repo signal에서 알 수 있는 건 먼저 추론한다\n3. durable하게 남아야 할 빈칸만 짧게 묻는다\n4. harness 파일을 생성하거나 repair한다\n5. 지금 harness가 healthy한지 알려준다\n```\n\n결과:\n\n- `PROJECT_HARNESS.md`가 사람이 읽는 계약 기준이 된다\n- `harness-contract.json`이 기계가 읽는 durable contract를 담는다\n- `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`는 얇은 projection으로 정렬된다\n- audit / completion check로 지금 harness가 healthy한지 검증할 수 있다\n\n## `skills.sh`로 설치\n\n```bash\nnpx skills add parkjangwon/make-harness\n```\n\n특정 에이전트에만 설치하려면:\n\n```bash\nnpx skills add parkjangwon/make-harness -a claude-code\nnpx skills add parkjangwon/make-harness -a codex\nnpx skills add parkjangwon/make-harness -a gemini-cli\n```\n\n설치 전에 노출되는 스킬을 먼저 확인하려면:\n\n```bash\nnpx skills add parkjangwon/make-harness --list\n```\n\n관리 파일은 아래 여섯 개입니다.\n\n- `AGENTS.md`\n- `CLAUDE.md`\n- `GEMINI.md`\n- `PROJECT_HARNESS.md`\n- `harness-contract.json`\n- `harness-runtime.json`\n\n## 핵심 원칙\n\n- `PROJECT_HARNESS.md` + `harness-contract.json`이 영속 계약의 기준이다\n- `harness-runtime.json`은 인터뷰 진행, 감지 결과, sync 메타데이터 같은 휘발성 상태만 담는다\n- `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`는 얇은 projection이다\n- durable 계약에는 오래 유지할 기본값과 가드레일만 넣는다\n- drift는 보여야 하고 repair 가능해야 한다\n- 더 강한 프레임워크와 전문 스킬 옆에서 조용히 공존해야 한다\n- 프로젝트 로컬 보안 가드레일은 계약에 넣고, 리포에는 lightweight path-based guardrail smoke check만 둔다\n\n## 공유 계약 필드\n\n- `communication_language`\n- `project_type`\n- `definition_of_done`\n- `change_posture`\n- `change_guardrails`\n- `verification_policy`\n- `approval_policy`\n- `project_commands`\n- `project_constraints`\n- `rule_strengths`\n- `communication_tone`\n- `stack_summary`\n- `environment`\n\n`rule_strengths`는 계약의 최소 enforcement layer야. 각 durable rule이 advisory / guided / enforced 중 어느 강도로 다뤄져야 하는지 표현하되, 하네스를 무거운 실행 프레임워크로 키우지는 않는다.\n\n## 경계선 필드: 방법론이 아니라 저장소 로컬 규칙으로 다뤄야 한다\n\n몇몇 필드는 이름만 보면 범위가 넓어 보일 수 있지만, `make-harness` 안에서는 반드시 저장소 로컬 의미로만 다뤄야 한다.\n\n- `definition_of_done` = 이 저장소의 기본 완료 기준 또는 local completion gate\n- `verification_policy` = 이 저장소의 기본 검증 규칙\n- `approval_policy` = 위험하거나 민감한 변경에 대한 이 저장소의 확인 규칙\n- `change_posture` = 이 저장소에서 변경 범위를 어느 정도 보수적으로 볼지에 대한 좁은 기본값\n\n반대로 planning, TDD, branch strategy, code review loop, brainstorming, sub-agent coordination 같은 것은 더 강한 상위 workflow 레이어에서 다룰 일이지, durable harness contract에 강하게 저장할 일이 아니다.\n\n## 동작 모드\n\n\n- `bootstrap`: 하네스가 아직 없음\n- `update`: healthy 하네스면 같은 `/make-harness` 명령에서 보강/수정 모드로 들어감\n- `repair`: 파일 누락, 계약 drift, invariant 파손이 있음\n\n## 인터뷰\n\n하네스는 저장소를 먼저 보고, 남는 불확실성만 짧게 묻습니다. 언어는 영어 고정 시작이 아니라 detect-first 원칙을 따릅니다. README, 디렉터리, 기존 문맥 등으로 협업 언어 힌트를 먼저 잡고, 확신이 부족할 때만 확인 질문을 합니다.\n\n인터뷰는 다음 원칙으로 더 구체적으로 고정되어 있습니다.\n\n- 이건 one-time setup이므로, 질문 수를 무작정 줄이는 것보다 정확한 규칙 확정이 더 중요\n- 기존 저장소는 repo-first gap-filling 방식으로, 코드 분석 후 정말 필요한 것만 확인\n- 빈 프로젝트는 코드가 없으므로 stack/runtime/package manager를 정하는 소규모 setup-discovery 질문을 먼저 진행\n- durable default용 고정 질문 순서 사용\n- 저장소 confidence에 따른 분기 규칙 사용\n- 일반적인 저장소에서는 명시 질문 5개 이하를 목표로 하되, 빈 프로젝트는 필요한 경우 더 촘촘히 물을 수 있음\n- change posture, approval policy, verification policy 같은 자유 응답을 canonical 값으로 정규화\n- `harness-runtime.json`이 중간 상태를 가리키면 resume 규칙과 contradiction 규칙 적용\n- 보안 민감 영역, 금지 secret/debug 패턴, 설정 기반 TLS 예외 규칙, 추가 보안 검증 명령처럼 꼭 필요한 최소 보안 인터뷰 항목 포함\n\n자세한 규칙은 [references/interview-guide.md](references/interview-guide.md), [references/interview-protocol.md](references/interview-protocol.md)를 참고하세요.\n\n## durable / volatile 분리\n\n### `harness-contract.json`\n\n커밋 대상입니다. 기계가 읽을 수 있는 영속 프로젝트 계약을 담습니다.\n\n### `harness-runtime.json`\n\n영속 계약의 기준 파일이 아닙니다. 인터뷰 진행 상태, 언어 감지 힌트, sync 메타데이터, audit 타임스탬프 같은 휘발성 상태만 담습니다.\n\n공유 저장소에서는 `harness-runtime.json`을 `.gitignore`에 넣는 것을 권장합니다. 기본 템플릿은 [assets/templates/.gitignore-harness](assets/templates/.gitignore-harness)에 있습니다.\n\n## healthy의 의미\n\n- 관리 파일이 모두 존재한다\n- 영속 canonical source가 같은 계약을 가리킨다\n- 엔트리 파일이 얇고 같은 계약 요약을 반영한다\n- runtime invariant가 유지된다\n- sync metadata가 healthy하다\n\n자세한 기준은 [assets/healthy-checklist.md](assets/healthy-checklist.md)에 정리되어 있습니다.\n\n## fixture 검증\n\n```text\npython tools/validate-fixtures.py\n```\n\n이 검증기는 이제 `tools/interview_planner.py`의 deterministic interview planner와도 교차 검증합니다. 즉 blank project에서 runtime/package manager discovery를 물어야 하는지, detect-first language confirmation이 맞는지, resume 시 다음 질문이 무엇인지가 문서 설명에만 머물지 않고 fixture 레벨에서 고정됩니다.\n\n## 가벼운 audit\n\n```text\npython tools/audit-harness.py /path/to/project\n```\n\n이 명령은 LLM 없이도 파일 구성, contract/runtime 분리, 엔트리 파일 두께, 핵심 runtime invariant를 검사합니다.\n\n## 결정적 projection 생성기\n\n`harness-contract.json`과 `harness-runtime.json`에서 바로 `PROJECT_HARNESS.md`, `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`를 기계적으로 생성하려면 다음을 실행하세요:\n\n```text\npython tools/apply-harness.py /path/to/project\n```\n\n이 도구는 리포 안에서 가장 작은 실행 계층이다. LLM이 durable contract를 결정하더라도 projection file은 손으로 다시 쓰지 않게 해준다.\n\n## 완료 게이트\n\n하네스가 단순히 존재하는 수준이 아니라 실제로 완료 가능한 상태인지 확인하려면 다음을 실행하세요:\n\n```text\npython tools/check-harness-done.py /path/to/project\n```\n\n이 게이트는 audit 성공, `configured` + `healthy` 상태, 전체 `validated_shared_fields`, 그리고 현재 projection이 deterministic generator 출력과 완전히 일치하는지를 요구한다.\n\n## 구조\n\n```text\nmake-harness/\n├── SKILL.md\n├── README.md\n├── README.ko.md\n├── docs/\n│   ├── coexistence.md\n│   └── positioning.md\n├── agents/\n│   ├── openai.yaml\n│   └── gemini.yaml\n├── tools/\n│   ├── apply-harness.py\n│   ├── audit-harness.py\n│   ├── check-harness-done.py\n│   ├── check-sensitive-change.py\n│   ├── interview_planner.py\n│   └── validate-fixtures.py\n└── assets/\n    ├── templates/\n    ├── fixtures/\n    ├── examples/\n    ├── healthy-checklist.md\n    └── repair-playbook.md\n```\n\n## 가벼운 경로 기반 guardrail smoke check\n\n다음 명령으로 auth / 권한 / secret / 결제 / 암호화 / public API 영역을 건드리는 변경을 감지할 수 있다:\n\n```text\npython tools/check-sensitive-change.py /path/to/project --paths src/auth/login.py config/tls-dev.yaml\n```\n\ngit ref 기준으로 검사하려면 다음처럼 실행한다:\n\n```text\npython tools/check-sensitive-change.py /path/to/project --base HEAD~1 --head HEAD\n```\n\n관련 `rule_strengths`가 `enforced`면 민감한 변경은 완료/CI/hook 단계에서 차단된다. `guided`면 카테고리를 보고만 하고 막지는 않는다.\n\n이 checker는 의도적으로 가볍다. 현재는 깊은 코드 분석기가 아니라 path-based smoke check다.\n\n## hooks와 CI\n\n- CI는 이제 `audit-harness`, `check-harness-done`, diff-sensitive smoke check를 함께 실행한다.\n- 샘플 git hook은 `assets/templates/pre-commit-harness.sh`에 있다.\n- hook은 `HEAD~1..HEAD` 가정 대신 `git diff --cached --name-only --diff-filter=ACMR` 기준으로 staged file만 검사한다.\n- `MAKE_HARNESS_HOOK_MODE`는 `strict`(기본), `warn`, `off`를 지원한다.\n- hook은 `audit: pass`, `done-gate: pass`, `sensitive-change: pass` 같은 짧은 요약을 출력해서 실패 이유를 더 읽기 쉽게 만든다.\n\n성공 예시:\n\n```text\nPASS: managed files present, contract/runtime split detected, entry files thin\n```\n\n실패 예시:\n\n```text\nmissing managed files: ['harness-contract.json', 'harness-runtime.json']\n```\n\n## 빠른 판단 가이드\n\n다음 상황이면 `make-harness`가 잘 맞습니다.\n\n- `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`가 계속 어긋난다\n- 무거운 프레임워크 없이 프로젝트 로컬 기본 계약만 안정화하고 싶다\n- 레거시 저장소의 숨은 제약을 한 번 정리해 재사용하고 싶다\n\n반대로 아래라면 맞지 않을 수 있습니다.\n\n- 저장소가 일회성이다\n- 문제의 본질이 contract가 아니라 execution orchestration이다\n- 플러그인, 런타임 툴, 에이전트 팀 관리까지 기대한다\n\n## 더 보고 싶다면\n\n- 포지셔닝: [docs/positioning.md](docs/positioning.md)\n- 공존 원칙: [docs/coexistence.md](docs/coexistence.md)\n- fixture: [assets/fixtures](assets/fixtures)\n- fixture 검증기: [tools/validate-fixtures.py](tools/validate-fixtures.py)\n- interview planner: [tools/interview_planner.py](tools/interview_planner.py)\n- lightweight audit: [tools/audit-harness.py](tools/audit-harness.py)\n- sample output: [assets/examples](assets/examples)\n- 도입 예시: [assets/examples/legacy-webapp-rollout.md](assets/examples/legacy-webapp-rollout.md)\n- 인터뷰 가이드: [references/interview-guide.md](references/interview-guide.md)\n- 인터뷰 프로토콜: [references/interview-protocol.md](references/interview-protocol.md)\n- repair playbook: [assets/repair-playbook.md](assets/repair-playbook.md)\n- healthy checklist: [assets/healthy-checklist.md](assets/healthy-checklist.md)\n- gitignore 템플릿: [assets/templates/.gitignore-harness](assets/templates/.gitignore-harness)\n\n## 사용 예시\n\n```text\n/make-harness\n```\n\n```text\n하네스가 없으면 bootstrap, 이미 healthy하면 update, 깨져 있으면 repair 후 이어서 진행하는 단일 엔트리 `/make-harness` 명령입니다.\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fparkjangwon%2Fmake-harness","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fparkjangwon%2Fmake-harness","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fparkjangwon%2Fmake-harness/lists"}