runesleo/claude-code-workflow

QuietHarness – AI 코딩 에이전트를 위한 가벼운 신뢰성 계층

무엇인가요

Claude Code, Codex, 또는 Cursor 와 같은 AI 코딩 어시스턴트에 안전 검사를 추가하는 작고 이식 가능한 설정 파일 및 스크립트 세트입니다.
핵심(1 604 bytes)은 "작업 경계"를 정의합니다: 관련 없는 변경 사항 탐지, 테스트 실행, 불가역 작업(예: 인증 정보 변경, 배포) 전에 확인 요구, 검증 가능한 감사 기록 유지.
세 가지 지원 에이전트 중 어느 것과도 호환되며, 사용하는 클라이언트에 맞는 부분만 설치하면 됩니다.

왜 필요할까

에이전트가 검토하지 않은 파일을 덮어쓰는 것을 방지합니다.
프로젝트의 테스트 스위트를 실행하지 않고 작업 완료라고 주장하는 것을 멈춥니다.
실제 파일 시스템에 변경 사항이 기록되기 전에 드라이런 미리보기를 보장합니다.
에이전트의 설정 파일을 자동 백업/롤백하여 이전 상태로 안전하게 되돌릴 수 있습니다.

구조

폴더	목적
`templates/`	세 가지 최소 설정 번들(공유 코어, Claude 어댑터, Cursor 규칙, Codex 어댑터).
`scripts/`	헬퍼 스크립트: 인벤토리, 설치(드라이런 및 적용), 검증, 마이그레이션.
`examples/first-success/`	에이전트의 "초기 실행"이 성공하는 단계별 격리된 데모.
`examples/leo-system/`	저자의 실제 작업 시스템의 정제된 스냅샷(JSON 예제, 문서).
`docs/`	아키텍처, 작업 지속성, 세션 종료 처리, 일일 보고서 처리 등.
`tests/`	일시적인 HOME 디렉터리에서 설치 프로그램을 실행하는 스모크 테스트.
`media/`	다이어그램 및 릴리스 그래픽.

일반 워크플로우

리포지토리 클론 후 ./scripts/inventory.sh 실행하여 영향을 받는 항목 확인.
격리된 데모 디렉터리 생성 (mktemp …).
클라이언트용으로 드라이런 모드에서 설치 프로그램 실행, 예:
```
./scripts/install.sh --dry-run --claude-project "$demo_dir"
```
미리보기 확인 후 --apply로 적용.
$demo_dir에서 선택한 에이전트 열고 Read TASK.md and complete the task. 와 같은 간단한 지시어 제공.
에이전트는 필요한 변경 사항을 수행하고 기존 테스트를 실행하며, 추가 프롬프트 없이 성공의 구체적 증거를 반환해야 합니다.
모든 것이 정상 작동하면 --project 플래그 없이 다시 설치 단계를 반복하여 코어를 전역으로 설치(~/AGENTS.md, ~/.claude/CLAUDE.md 등에 기록). 백업은 자동 생성됨(.bak-ai-workflow-*).

핵심 안전 메커니즘

드라이런 미리보기 – --apply를 명시적으로 전달하지 않으면 파일이 쓰이지 않습니다.
백업 및 롤백 – 원본 설정 파일은 타임스탬프와 함께 저장되며, 설치 프로그램이 자동으로 복원할 수 있습니다.
위험 게이트 작업 – 인증 정보 변경, 프로덕션 배포, 게시와 같은 잠재적으로 파괴적인 작업은 에이전트의 명시적 확인 단계가 필요합니다.
격리 – 데모는 일시 디렉터리 내에서 완전히 실행되며, 설치 프로그램은 인터넷에 접속하지 않으며 계정 설정을 수정하지 않습니다.

누구를 위한 것인가

코드 생성에 이미 Claude Code, Codex, 또는 Cursor를 의존하는 개발자로서, 실수로 파일을 덮어쓰거나 검증되지 않은 커밋을 방지하기 위한 보호 장치가 필요한 사람.
이러한 에이전트 간을 전환하는 팀으로, 도구 간 이식 가능한 일관된 안전 정책이 필요하며, 규칙을 다시 작성하지 않아도 되는 사람.
자신의 코드베이스에서 AI 어시스턴트가 신뢰할 수 있게 동작하는지 검증하기 위한 재현 가능한 "초기 성공" 온보딩 테스트를 찾는 사람.

제한 사항

작업 데이터베이스, 스케줄러, 팀 전체 오케스트레이션 플랫폼은 제공하지 않습니다. 별도로 구축해야 합니다.
유닉스 유사 쉘만 지원되며, Windows용 PowerShell 설치 프로그램은 아직 없습니다.
핵심 규칙은 정적 텍스트 파일이며, 확장하려면 수동 편집 또는 자체 템플릿 구축이 필요합니다.
각 AI 에이전트 클라이언트가 로컬에 설치 및 설정되어 있다고 가정합니다.

설치 및 검증

# 클론 및 확인
git clone https://github.com/runesleo/claude-code-workflow.git
cd claude-code-workflow
./scripts/verify.sh   # 스모크 테스트 실행, 백업 확인, 템플릿 크기 등 검사

검증 후 위의 데모 단계를 따르거나 전역 설치를 실행:

# Claude Code (사용자 수준)
./scripts/install.sh --dry-run --claude
./scripts/install.sh --apply --claude

Codex(--codex) 및 Cursor(--cursor)용 유사한 명령어도 존재합니다.

라이선스

MIT 라이선스(LICENSE 참조).

QuietHarness 는 본질적으로 AI 코딩 어시스턴트가 더 예측 가능하고 안전하게 동작하도록 하는 설정을 코드로 표현한 패키지입니다. 네트워크 호출이나 프로퍼라이어터리 API를 필요로 하지 않으며, LLM 기반 코드 어시스턴트와 작업하는 개발자에게 진정한 재사용 가능한 도구입니다.

runesleo/claude-code-workflow

QuietHarness – AI 코딩 에이전트를 위한 가벼운 신뢰성 계층

관련