QuietHarness – AI 코딩 에이전트용 경량 안전 레이어

정의 – QuietHarness는 Claude Code, Codex, Cursor와 같은 AI 기반 코딩 어시스턴트에 '안전 하네스'를 추가하는 작고 휴대 가능한 구성 파일 및 헬퍼 스크립트 세트입니다. 이 하네스는 모델을 변경하거나, 외부 서비스를 호출하거나, API 키를 요구하지 않습니다. 대신 공유 코어(약 1.6KB)를 설치하여 몇 가지 안정성 규칙을 적용합니다.

관련 없는 파일을 덮어쓰지 마세요 – 에이전트는 먼저 저장소의 현재 상태를 확인해야 합니다.
성공을 선언하기 전에 테스트를 실행하세요.
위험한 작업(예: 자격 증명 변경, 프로덕션 배포)은 확인 단계로 취급하세요.
변경된 사항에 대한 구체적인 증거를 기록하여 나중에 검증할 수 있도록 하세요.

동일한 코어는 지원되는 세 에이전트 모두에서 사용할 수 있습니다. 설치 프로그램은 선택한 도구에 따라 적절한 템플릿 파일(예: Claude Code/Codex용 AGENTS.md, Cursor용 quiet-harness.mdc)을 작성합니다.

누가 혜택을 받을 수 있나요?

이미 AI 코딩 어시스턴트에 의존하고 있으며 파일 덮어쓰기, 테스트 누락, 검토되지 않은 파괴적 작업 등의 문제를 겪은 개발자.
Claude Code, Codex, Cursor 사이를 전환하며 매번 구성을 다시 만들지 않고 일관된 안전 검사를 원하는 팀.
드라이런 우선 워크플로를 찾는 사람. 롤백이 가능합니다(백업은 타임스탬프와 함께 자동 생성).

빠른 시작(격리된 데모)

# 리포지토리 클론 및 진입
git clone https://github.com/runesleo/claude-code-workflow.git
cd claude-code-workflow

# 인벤토리 검사 실행(정상 작동 확인 스크립트)
./scripts/inventory.sh

# 데모용 임시 샌드박스 생성
DEMO=$(mktemp -d /tmp/quiet-harness-demo.XXXXXX)
./examples/first-success/setup.sh "$DEMO"

세 에이전트 중 하나를 선택하고 드라이런 모드로 설치 프로그램을 실행한 후 적용합니다.

# Claude Code 예시
./scripts/install.sh --dry-run --claude-project "$DEMO"
./scripts/install.sh --apply   --claude-project "$DEMO"

설치 프로그램은 하네스 파일을 샌드박스에 작성하고(AGENTS.md, CLAUDE.md 또는 Cursor 규칙 파일) 무엇을 백업할지 보고합니다.

내부 작동 방식

레이어	내용	크기
공유 코어	`templates/shared/AGENTS.md` – 보편적인 안전 규칙	1,604B
Claude Code 어댑터	`templates/claude/CLAUDE.md` – 코어를 가리키는 얇은 래퍼	168B
Cursor 규칙	`templates/cursor/quiet-harness.mdc` – Markdown 호환 규칙 파일	546B

선택한 에이전트는 이 파일 중 하나만 로드하고 나머지는 비활성 상태로 둡니다. 코어는 네 가지 동작 범주를 정의합니다.

직접 요청 실행 – 에이전트는 하네스가 요청을 확인한 후에만 진행합니다.
가시성 검사 – 에이전트는 파일, 웹페이지 또는 기록을 검토했다고 주장하기 전에 명시적으로 읽어야 합니다.
위험 기반 검증 – 파일 변경 후 하네스는 모델에게 위험 프로필에 대해 변경 사항을 검증하도록 요청합니다.
되돌릴 수 없는 작업 확인 – 자격 증명, 프로덕션 또는 재정에 영향을 줄 수 있는 모든 작업에는 명시적인 사용자 확인 단계가 필요합니다.

선택적 실험용 랩

리포지토리에는 하네스를 확장하는 방법을 보여주는 몇 가지 랩이 포함되어 있습니다:

Attention Inbox – 사소한 waiting_for_user 메시지를 필터링하고 실제 결정 지점만 표시합니다.
Chat Export – Claude Code, Codex, Cursor, Grok Bot의 로컬 채팅 로그를 단일 Markdown 형식으로 정규화합니다.
Session Hooks – 스레드 이름 변경, 종료 체크리스트 줄 추가, 보류 중인 결정 중복 제거를 알리는 작은 hooks.
OPC Company Layer – 다중 소유자/작업자 핸드오프를 위한 실험적 거버넌스 레이어 (기본 하네스에는 필요 없음).

이러한 랩은 선택 사항이며 labs/ 아래에 있습니다.

설치 및 롤백

설치 프로그램은 기존 파일을 덮어쓰기 전에 타임스탬프가 있는 백업(.bak-ai-workflow-*)을 생성합니다.
--dry-run은 작성될 내용을 정확히 표시하고, --apply는 변경 사항을 적용합니다.
--undo 스타일 롤백은 백업을 복원하고 새로 생성된 파일을 제거하여 가능합니다 (MIGRATION-v3.md#回滚 참조).
사용자 수준 설치는 ~/AGENTS.md(Claude) 또는 $CODEX_HOME/AGENTS.md(Codex)에 영향을 미칩니다. 프로젝트 수준 설치는 --*프로젝트로 전달한 대상 디렉토리에 작성합니다.

검증 및 테스트

./scripts/verify.sh를 실행하면 다음을 확인합니다:

셸 구문 및 설치 프로세스 격리.
드라이런, 다중 대상 사전 점검, 백업 및 롤백의 올바른 처리.
개인 경로 또는 실시간 작업 데이터의 우발적 유출 없음.
템플릿 크기 제한(총 2,318B).
시스템 맵 및 예제 작업 파일의 기본 SVG/JSON 무결성.

사용 시기(및 사용하지 않을 때)

QuietHarness를 사용하세요 – 이미 AI 코딩 어시스턴트가 있고 프로젝트와 함께 버전 관리할 수 있는 가볍고 재현 가능한 안전망이 필요한 경우.

전체 작업 오케스트레이션 플랫폼으로 사용하지 마세요 – 작업 데이터베이스, 스케줄러 또는 팀 차원의 조정 기능을 의도적으로 제공하지 않습니다. 이러한 기능은 별도의 시스템에 속합니다 (README는 저자의 다른 리포지토리를 참조하도록 안내).

라이선스

MIT – LICENSE 파일을 참조하세요.

TL;DR

QuietHarness는 Claude Code, Codex 또는 Cursor 작업 공간에 드롭인할 수 있는 2KB 구성 번들로, 어시스턴트가 더 예측 가능하게 동작하도록 합니다: 파일을 백업하고, 테스트 실행을 강제하고, 위험한 작업에 대한 명시적 확인을 요구하며, 변경 사항에 대한 구체적인 증거를 기록합니다. 단일 스크립트로 설치하고, 격리된 샌드박스에서 시도하고, 필요 시 쉽게 롤백할 수 있습니다.

runesleo/claude-code-workflow