parkjangwon/make-harness

make-harness은(는) 무엇을 하나요?

사용자가 현재 리포지토리에서 프로젝트 로컬 하네스를 설정, 감사, 업데이트 또는 복구하려고 할 때 이 스킬을 사용하세요.

이 스킬은 부트스트래퍼이자 유지보수 진입점입니다. 실제 프로젝트 계약은 스킬 자체가 아닌 대상 프로젝트의 로컬 파일에 있어야 합니다.

이 스킬이 관리하는 것

다음 프로젝트 로컬 파일을 생성, 업데이트 또는 복구합니다:

• AGENTS.md
• CLAUDE.md
• GEMINI.md
• PROJECT_HARNESS.md
• harness-contract.json
• harness-runtime.json

템플릿 소스는 assets/templates에 있습니다. tools/apply-harness.py를 사용하여 계약/런타임 쌍에서 투영 파일을 결정론적으로 재생성합니다. tools/check-harness-done.py를 하네스 완료 처리 전 완료 게이트로 사용합니다. tools/check-sensitive-change.py를 CI, 훅 또는 리뷰어가 현재 diff가 민감한 영역에 닿는지 확인하기 위한 결정론적이고 가벼운 경로 기반 스모크 검사가 필요할 때 사용합니다.

핵심 동작

1. 먼저 현재 리포지토리와 기존 하네스 파일을 검사합니다.
2. /make-harness를 단일 진입 명령으로 처리합니다: 하네스가 없으면 bootstrap, 정상 하네스가 이미 있으면 update, 드리프트나 손상이 감지되면 repair.
3. 내구성 있는 프로젝트 계약을 PROJECT_HARNESS.md와 harness-contract.json에 유지합니다.
4. 인터뷰 진행 상황, 동기화 메타데이터 및 언어 감지 힌트는 harness-runtime.json에만 저장합니다.
5. 하네스가 불완전하거나 내구성 있는 기본값이 없으면, 기본값을 최종으로 처리하기 전에 짧은 인터뷰를 시작합니다.
6. 한 번에 한 질문씩 대화형으로 인터뷰를 진행합니다.
7. 먼저 리포지토리 신호에서 협업 언어를 감지합니다. 불명확할 때만 확인하며 영어 우선 오프너를 강제하지 않습니다.
8. 각 답변 후 런타임 진행 상황을 harness-runtime.json에 반영하고 내구성 있는 답변을 harness-contract.json에 반영합니다.
9. 내구성 있는 프로젝트 기본값, 프로젝트 로컬 보안 가드레일 및 실행 가드레일만 확인합니다.
10. 최소한의 적용 의도를 rule_strengths에 기록하여 계약이 권고, 안내 및 강제 규칙을 구분할 수 있도록 합니다.
11. AGENTS.md, CLAUDE.md 및 GEMINI.md를 얇게 유지합니다. 내구성 있는 계약은 PROJECT_HARNESS.md에 두고, 진입 파일은 포인터와 요약 규칙으로 유지합니다.
12. 관리되는 하네스 파일이 확인된 계약에 동의하는지 검증합니다. 드리프트가 감지되면 완료 전에 복구합니다.
13. 성공 선언 전에 완료 게이트를 실행합니다: 감사 통과, 런타임 상태 정상, 검증된 공유 필드 완료, 결정론적 투영이 체크인된 파일과 일치해야 합니다.
14. 현재 diff가 민감한 영역에 닿을 때는 가벼운 경로 기반 가드레일 스모크 검사를 사용하여 CI/훅이 강제된 가드레일이 적용될 때 결정론적으로 실패할 수 있도록 합니다.
15. 훅 통합의 경우 HEAD~1..HEAD 추측보다는 스테이지된 파일 검사를 선호하고, 교차 프로젝트 명명 잔재 대신 MAKE_HARNESS_HOOK_MODE를 사용하며, 단일 하드코딩된 동작 대신 작은 strict / warn / off 모드 스위치를 허용합니다.
16. 내구성 있는 프로젝트 계약이 변경될 때마다 간결한 변경 내역 항목을 기록합니다.
17. bugfix, feature, maintenance 또는 refactor와 같은 요청별 작업 유형을 영구 하네스 상태로 저장하지 않습니다.
18. 프레임워크 수준의 오케스트레이션 선호도를 영구 하네스 상태로 저장하지 않습니다.

실행 분류

harness-contract.json과 harness-runtime.json이 있으면 읽습니다.

• 하네스가 없으면 부트스트랩합니다.
• 하네스가 있고 정상이면 업데이트 모드로 진입합니다.
• 하네스가 있지만 드리프트되었거나 손상되었으면 먼저 복구하고 필요한 경우에만 업데이트를 계속합니다.
• bootstrap_status가 pending_interview이면 하네스가 아직 구성되지 않은 것입니다.
• bootstrap_status가 interview_in_progress이면 기록된 런타임 상태부터 재개합니다.

대화형 인터뷰 흐름

• 한 번에 정확히 한 질문만 합니다.
• 이는 일회성 설정 흐름이므로 질문 수 최소화보다 정밀도가 더 중요합니다.
• 기존 리포지토리의 경우 리포지토리 우선 인터뷰 동작을 사용합니다: 먼저 검사하고 추론한 다음 불명확한 것만 확인합니다.
• 빈 프로젝트의 경우 설정-발견 인터뷰 동작으로 전환합니다: 스택, 런타임, 패키지 관리자 및 핵심 명령어를 선택하는 데 필요한 소수의 사전 질문만 합니다.
• references/interview-protocol.md의 고정된 질문 순서를 따릅니다.
• 리포지토리가 이미 가능성 있는 답변을 제공하는 경우 개방형 질문보다 확인 질문을 선호합니다.
• 일반적으로 추론 가능한 메타데이터에 대해 묻기보다 리포지토리를 검사하는 것을 선호합니다.
• 감지 우선 언어 선택을 사용합니다:
  • README 언어, 기존 루트 문서, 주석 및 파일 명명 패턴을 찾습니다.
  • 한 언어가 강력하게 암시되면 확인 어조로 시작합니다.
  • 신호가 약하거나 혼합되면 일반 영어로 언어 질문을 합니다.
• 프로토콜의 인터뷰 질문 예산을 준수합니다:
  • 일반 리포지토리의 경우 명시적 질문 5개 이하를 목표로 합니다.
  • 8개를 정당화가 필요한 소프트 상한선으로 간주합니다.
• 간단한 사용자 답변을 상태를 쓰기 전에 표준 저장 값으로 정규화합니다.
• project_type, change_posture, approval_policy, verification_policy 및 communication_tone에 대해 references/interview-protocol.md의 표준 정규화 테이블을 사용합니다.
• 내부 스키마 이름을 직접 노출하는 대신 references/interview-protocol.md의 사용자 대상 질문 템플릿을 사용합니다.
• 자신감(high, medium, low)에 따라 프로토콜의 3단계 템플릿 매트릭스에서 표현을 선택합니다.
• 인터뷰가 영어로 진행될 때는 임시 번역 대신 프로토콜의 영어 동반 템플릿을 사용합니다.
• 사람 레이블이 아닌 답변에 따라 적응합니다: 사용자의 실제 응답 패턴에 따라 정밀 모드, 명확화 모드 및 안전 기본값 모드 사이를 전환합니다.
• pending_fields와 confirmed_fields를 비중첩 집합으로 정규화합니다.
• 리포지토리에서 파생된 추측을 확인될 때까지 임시 추론으로 간주합니다.
• bootstrap_status가 interview_in_progress이면 다시 시작하는 대신 기록된 interview_step부터 재개합니다.
• 새 사용자 답변이 내구성 있는 상태나 강력한 리포지토리 신호와 모순을 만들면 계약을 덮어쓰기 전에 확인합니다.
• 필요한 모든 내구성 있는 기본값이 확인된 경우에만 bootstrap_status를 configured로 설정합니다.

출력 파일

부트스트랩, 업데이트 또는 복구 후 대상 프로젝트에는 다음이 있어야 합니다:

• 얇은 AGENTS.md
• 얇은 CLAUDE.md
• 얇은 GEMINI.md
• 사람이 읽을 수 있는 PROJECT_HARNESS.md
• 기계가 읽을 수 있는 내구성 있는 harness-contract.json
• 기계가 읽을 수 있는 휘발성 harness-runtime.json

리소스

• 템플릿: assets/templates
• 공존: docs/coexistence.md
• 인터뷰 가이드: references/interview-guide.md
• 인터뷰 프로토콜: references/interview-protocol.md
• 복구 및 검증 가이드: references/repair-validation-guide.md
• 검증 픽스처: assets/fixtures
• 인터뷰 플래너: tools/interview_planner.py — 테스트 및 픽스처에서 빈 프로젝트 발견, 리포지토리 우선 확인, 재개 순서 및 답변 모드 적응을 고정하는 결정론적 헬퍼
• 복구 플레이북: assets/repair-playbook.md
• 정상 체크리스트: assets/healthy-checklist.md
• 샘플 출력: assets/examples
• 로컬 감사 도구: tools/audit-harness.py — 관리되는 파일, PROJECT_HARNESS.md 구조, 진입점 얇음 및 런타임 불변량을 확인합니다.
• 결정론적 투영 생성기: tools/apply-harness.py — 표준 계약/런타임 파일에서 PROJECT_HARNESS.md, AGENTS.md, CLAUDE.md 및 GEMINI.md를 재생성합니다.
• 완료 게이트: tools/check-harness-done.py — 하네스가 완료된 것으로 처리되기 전에 감사 성공, 정상 런타임 상태, 완전한 검증된 공유 필드 및 투영 드리프트 없음을 요구합니다.
• Diff 민감 가드레일 검사기: tools/check-sensitive-change.py — 인증/권한/비밀/결제/암호화/공개 API에 닿는 diff에 대한 가벼운 경로 기반 스모크 검사; 관련 규칙 강도가 강제된 경우에만 차단합니다.
• 포지셔닝: docs/positioning.md
• 기여: CONTRIBUTING.md
• 선택적 UI 메타데이터: agents/openai.yaml, agents/gemini.yaml