그냥 묻고, 확인만 하면 돼.

oah는 git과 pull request를 이미 쓰는 개발자와 작은 팀이 자기 컴퓨터에서 실무 수준의 검토 절차를 지키도록 돕는다. AI 코딩 결과가 아쉽거나 처음 하네스를 꾸리는 사람을 가장 먼저 생각하고 만들었다.

현재 릴리스인 v0.3.0은 여전히 git과 pull request에 익숙한 사용자를 전제로 한다. 브랜치에서 일하고, push하고, pull request를 열고, 반영을 직접 확인한다.

WSL 없이 macOS 13 이상과 Windows 11을 지원한다. Windows 10 22H2는 가능한 범위에서 지원한다. Linux는 아직 지원하지 않는다.

oah는 Python 3.11 이상과 표준 라이브러리만 쓴다. CI 스타터는 고르면 Linux 러너(ubuntu-latest)에서도 내 프로젝트를 테스트할 수 있지만, oah 자체가 도는 환경과는 별개다.

oah 자체는 MIT 라이선스이며 키가 필요 없다. 엔진은 사용자가 직접 설치하고 로그인한다. Claude Code는 Pro, Max, Team, Enterprise, Console 계정이 필요하고, Codex는 ChatGPT 요금제나 API 키를 받는다.

선택 기능은 각자의 조건이 있다. TypeSafe Jev는 자기 TypeSafe 계정과 키가 필요하고 TypeSafe는 요청마다 요금을 물릴 수 있다. Aside에는 무료 요금제가 있다. 비공개 GitHub 저장소에서 필수 검사 규칙 세트를 쓰려면 GitHub Pro, Team, Enterprise Cloud가 필요하다. 문서에 가격은 적혀 있지 않다.

설치 프로그램을 한 번 실행하고, 원격이 연결된 git 저장소인 프로젝트마다 oah init을 한 번 실행한 뒤 쓴 파일을 커밋한다. 그다음부터는 그 프로젝트에서 AI를 열고 “로그인 기능을 oah로 만들어 줘.”처럼 평소 말로 요청한다.

따라 하기 예제 examples/hello-oah는 작은 작업 하나를 전체 흐름에 태우며 20분쯤 걸린다. 내가 할 말, AI가 하는 일, 확인할 것을 먼저 보여 주고 전체 명령 예제를 이어 싣는다.

지금 oah 명령은 Claude Code와 Codex CLI를 움직인다. 리스, 엔진 단계, 증거 게이트, 영향 지도, 위키, 리뷰 루프 같은 아이디어는 다른 도구나 하네스를 포함해 AI 하나만 써도, 여러 AI를 함께 써도 적용할 수 있다. 필요한 부분을 가져가고 단계마다 자기에게 맞는 AI를 고른다.

oah 안에서는 .oah/config.toml의 [stages]가 단계마다 엔진을 정한다. 맞지 않는 엔진 호출은 거절되며 --override-stage를 주면 실행하되 기록한다. 한 엔진이 작성과 리뷰를 모두 맡으면 리뷰 영수증은 독립 리뷰가 아니라고 정직하게 적는다.

이 역할 분담은 만든 사람의 개인적인 경험에서 나왔고, 측정한 비교 결과는 아니다. 만든 사람이 써 보니 Claude는 첫 버전을 만들면서 초보자가 놓치기 쉬운 부분까지 채우는 데 강했고, Codex는 정해진 범위 안에서 검사하고 고치는 데 강했다.

그래서 Claude가 먼저 만들고 Codex가 검토, 수정, 재검토한다. 다른 분담이 맞으면 .oah/config.toml에서 단계 배정을 바꿀 수 있다.

아니다. Jev는 권장 선택형 판정기다. 키가 없거나 끄면 정해진 규칙이 판단하고, 결과에는 rerank=unused(no key)나 rerank=unused(not-enabled)가 표시된다. 키만으로는 켜지지 않는다. 직접 켜야 하며 oah init이 한 번 묻는다.

v0.3.0에서 Jev는 선택한 스킬의 순서를 다시 매기고 Intent와 Scope 경로로 난이도를 판정한다. 확신도가 충분할 때만 판정한 tier를 쓰고 위험도 하한 아래로 내려가지 않는다. 꺼짐, 실패, 낮은 확신도에서는 규칙이 판단한다. Jev 실패는 호출을 막지 않는다.

게이트는 사용자가 승인한 CHECK 명령을 unlazy로 실행해 EXPECT 출력이 나왔다는 것을 증명하며, 그 증거를 기록하고 입력에 묶는다. 나중에 입력이 바뀌면 게이트를 다시 돌리고, oah finish는 충족하지 못한 게이트를 거절한다.

명령이 확인하는 것 이상은 증명하지 않는다. 게이트의 입력은 추적 중인 파일, 무시되지 않은 미추적 파일, 실행 환경이므로 외부 서비스나 무시된 미추적 파일이 바뀌어도 다시 돌지 않는다. 그런 것은 따로 확인한다. oah review summary와 oah gates status는 체크 칸을 구조로만 읽고 아무것도 다시 실행하지 않으므로, 체크된 칸도 이미 낡았을 수 있다.

리스는 작업 하나가 바꿀 경로를 예약한다. 범위가 겹치는 두 번째 리스는 OAH_LEASE_CONFLICT로 거절하고 누가 잡고 있는지 알려 주므로, AI 세션 둘이 실수로 같은 파일에서 시작하지 않는다. 선택형 pre-push 훅을 설치하면 이 워크트리에 리스가 남아 있는 동안 push도 거절한다.

리스가 편집기의 다른 곳 쓰기를 막을 수는 없다. 대신 oah finish가 리스를 잡은 뒤 실제로 바뀐 파일을 범위와 대조하고 OAH_SCOPE_EXCEEDED로 거절한다. 리스는 기본 4시간 동안 유효하고 그 뒤에는 STALE로 보인다.

라운드마다 범위 안의 새 지적이 나오는 동안 이어 간다. P0와 P1 지적은 막고 oah fix로 고친다. 승인이 나오거나 P2와 P3 지적만 남은 라운드에서 시리즈가 끝나고, 남은 지적은 후속 작업으로 기록한다.

꼭 필요할 때만 사용자에게 묻는다. 앞선 수정이 이미 고치려 한 종류의 지적이 다시 나오거나 고치는 데 설계나 저장 형식 변경이 필요하면 OAH_REVIEW_NEEDS_DECISION으로 멈춘다. 사용자가 결정한 뒤 oah review --task <task> --decision "<결정한 내용>"으로 이어 가면 기록된다.

라운드 수는 정해져 있지 않다. 상한을 두고 싶으면 [review] max_rounds를 설정한다. 닿으면 OAH_REVIEW_ROUNDS_EXHAUSTED로 멈추고, --extra-round로 이어 가면 기록되며, 상한을 올리거나 지울 수도 있다.

이와 별도로 한 라운드에서 리뷰어 호출이 세지 않고 여러 번 실패하면 oah는 OAH_REVIEW_ATTEMPTS_EXHAUSTED로 유료 리뷰어 호출을 멈춘다. 마지막 실행의 stderr.log를 읽고 원인을 고친 뒤 --extra-attempt로 다시 실행한다.

공유 규칙 블록이 에이전트에게 push와 강제 push를 금지하고, 반영은 사용자가 확인하는 명령이다. oah land --check는 정확한 head에서 리스, 의도, 리뷰, 게이트, 영향, 필수 검사, fast-forward, gitleaks 검사, CI를 확인한다.

oah land --merge는 모든 검사를 다시 돌리고 y 입력으로 확인을 받은 뒤, 원격 기본 브랜치가 방금 확인한 커밋과 여전히 같을 때만 정확히 리뷰한 head로 fast-forward한다. 검증되지 않은 CI는 head마다 명시적 예외를 기록하지 않는 한 막히고, 실패하거나 진행 중인 CI는 언제나 막힌다.

설치 프로그램은 비밀번호나 키를 보지 않는다. 비밀번호가 필요한 설치 프로그램은 직접 묻는다. Claude Code와 Codex는 자기 자격 증명을 각자 보관하고, oah는 상태 명령(claude auth status, codex login status)만 실행해 로그인 여부를 읽는다. 동반 앱 설정도 로그인 상태 칸만 보고 명령 출력은 버린다.

선택 기능의 키는 실행할 때만 환경 변수나 OS 키체인에서 읽는다. oah는 키를 파일에 붙여 넣으라고 하지 않고, 키를 쓰거나 출력하거나 지시문, 실행 기록, 오류 메시지에 넣지 않는다.

구현과 리뷰는 사용자가 로그인한 엔진인 Claude Code와 Codex가 한다. 스킬 선택 기록은 상태 폴더의 로컬 파일에만 남고 어디로도 보내지 않는다.

Jev를 켜면 요청은 TypeSafe로 간다. v0.3.0의 난이도 판정은 작업의 Intent 글과 Scope 경로를 16,000자까지 보내며 코드, diff, 파일 내용, 키는 보내지 않고, 개인정보 검사에 걸리면 아무것도 보내지 않는다. v0.3.0에서 모델 카탈로그를 다시 만들 때 Epoch AI의 공개 벤치마크 파일을 받는데, 그 요청에는 프로젝트, 작업, 사용자에 관한 것이 들어가지 않고 [models] fetch_scores = false로 멈출 수 있다.

확인하기 전에는 아무것도 바꾸지 않는다. oah init은 먼저 선택 사항마다 한 번씩 묻고, 도구와 로그인을 확인하고, 전체 계획을 보여 준다. 승인하면 .oah/config.toml, AGENTS.md의 규칙 블록(CLAUDE.md가 불러온다), docs/wiki/의 위키, .oah/templates/의 템플릿, 로컬 비밀 파일을 위한 .gitignore 항목을 쓰고 첫 영향 지도를 만든다. 쓴 파일은 커밋한다.

두 번째로 실행하면 아직 빠진 것만 쓴다. --force 없이는 기존 파일을 바꾸지 않고, 위키의 색인과 로그는 바꾸지 않는다. 동반 앱 단계 가운데 [global]이 붙은 것은 사용자 폴더의 파일을 바꾸며 단계마다 먼저 묻는다.

먼저 열린 리스를 끝내거나 내려놓는다. 클론에서는 git pull 뒤 --skip-tools(Windows는 -SkipTools)로 설치 프로그램을 다시 실행한다. 릴리스에서는 새 태그의 소스 압축 파일과 SHA256SUMS를 받아 지문이 일치한 뒤에만 푼다. 그다음 새 터미널에서 oah --version과 oah doctor를 확인한다.

프로젝트마다 oah rules check와 oah rules sync로 관리 규칙 블록을 새로 고치고, oah init은 빠진 것만 쓰며, oah models --refresh는 모델 목록을 다시 읽는다. 스킬, unlazy, MCP 템플릿 고정 버전은 업그레이드 문서에 각자의 업데이트 방법이 있다.

고정한 문서에는 oah 자체를 제거하는 방법이 적혀 있지 않다. 동반 앱을 지우는 방법(claude mcp remove aside --scope user, codex mcp remove aside, 앱 제거 등)은 있고, oah hooks가 선택형 훅을 지운다.

문서에 있는 복구 방법은 로그 옮기기가 중단된 뒤의 oah wiki recover, 맞지 않는 unlazy 사본을 옮겨 두고 oah init --with-unlazy 다시 실행, 끝내지 않고 리스를 내려놓는 oah release --reason, 그리고 키가 새어 나갔을 때 이력을 정리하기 전에 먼저 발급한 곳에서 키 바꾸기다.

모든 거절은 OAH_* 코드로 시작하고, 나머지 메시지가 관련된 파일, 리스, 게이트와 다음에 실행할 명령을 알려 준다. 종료 코드 1은 거절(메시지대로 고치고 다시 실행), 2는 사용법 오류나 사전 점검의 ABORT, 69는 환경 문제, 75는 실행이 진행 중인데 oah wait이 제한 시간에 닿았다는 뜻이다.

먼저 oah doctor를 실행하고 문제 해결 문서에서 코드를 찾는다. 자주 만나는 코드를 단계별로 묶어 뜻과 다음에 할 일을 적어 두었다. 그래도 막히면 oah status, oah intent show <task>, oah gates status <task>가 도움이 된다.

반영할 때 gh로 정확한 head의 CI 결과를 읽는다. gh가 없거나 결과가 없거나(워크플로를 설치하지 않은 경우 포함) 필수 검사 결과가 빠지면 CI는 unverified이고 기본적으로 반영을 막는다. --accept-unverified-ci "<reason>"으로 head마다 명시적 예외를 기록할 수 있지만 CI는 unverified로 남고 통과로 세지 않는다.

oah ci init은 보여 주고 물은 뒤 시작 워크플로를 쓴다. 고른 운영체제에서의 테스트와 버전을 고정한 gitleaks 검사가 들어 있고, 권한은 읽기 전용이며 action은 전체 커밋 SHA로 고정한다. oah는 저장소 설정을 바꾸지 않는다. 검사를 필수로 만드는 GitHub 규칙 세트는 사용자가 직접 더한다.

아니다. 둘 다 선택이며 oah는 이 앱 없이도 모두 동작한다. oah doctor는 둘을 optional로 표시하고, 선택 앱이 없다고 실패하지 않는다. 설정은 앱마다 무엇을 더해 주는지 한 줄로 설명하고 사용자가 확인한 것만 설치하며, --yes로는 설치하지 않는다.

Orca는 코딩 에이전트를 각자의 git 워크트리에서 나란히 돌리고, oah call --launcher orca로 워커를 Orca 터미널에서 실행할 수 있다. Aside는 AI 에이전트가 들어 있는 브라우저이고 Claude Code와 Codex가 MCP로 웹 작업에 쓴다. Linux에서는 돌지 않는다.

oah는 MIT 라이선스로 배포하며 저작권자는 open-agent-harness 기여자다. skills/의 스킬은 각 라이선스가 허락하는 것만 원본 그대로 싣고, 해당 라이선스와 출처 기록을 함께 둔다.

THIRD_PARTY_NOTICES.md에 바탕으로 삼은 diagram-design 템플릿(MIT), Tabler Icons(MIT), Epoch AI 벤치마크 자료(CC BY 4.0), 그리고 unlazy, superpowers, graphify, Claude Code, Codex CLI 등 oah가 실행하거나 연결하는 도구의 출처가 있다.

oah를 업데이트한 뒤 프로젝트마다 oah rules sync를 실행한다. oah --version 출력은 oah 0.3.0이다. 새 규칙은 AI가 설계 난이도를 먼저 판정하게 하며, 없으면 패킷 생성 때 OAH_DESIGN_UNJUDGED가 나온다. 사용자 설정은 고치지 않는다.

모델을 고정하지 않았다면 이제 점수로 모델을 고른다. 기존 프로젝트의 도구 업데이트는 꺼진 채로 남는다. Jev가 켜져 있으면 확장된 Intent·Scope를 처음 보낼 때 OAH_RERANK_SCOPE_WIDENED가 나온다. 하한, 고정 모델, 점수 다운로드와 Jev를 끄는 방법은 업그레이드 문서에 있다.

v0.3.0은 현재 공개된 릴리스이며 주제는 벤치마크로 고르는 모델이다. 벤치마크 점수가 performance, balanced, efficient 프로필에 따라 모델을 고르고, 점수는 키 없이 Epoch AI에서 가져오거나 자기 Artificial Analysis 키로 받는다. 새 세대 모델은 알림과 함께 자동으로 합류하고 빠지며, Jev가 Intent와 Scope 경로로 난이도를 판정하되 호출을 막지 않는 규칙 기반 대체가 있고, 리뷰는 위험도 하한 아래로 실행하지 않으며, 마지막 리스 뒤에 선택형 도구 업데이트가 돌고, oah models report와 내보내기가 선택 방식을 센다. 고정 모델, tier 후보, 추론 강도 상한, 작업별 최저 기준은 그대로 유지된다.

2026년 11월 4일 공개됐다. 고정된 설치 스크립트, 소스 압축 파일과 SHA256SUMS가 포함된다. 안내형 설계 대화는 계속 v0.4.0 계획이다.

안내형 설계 대화다. 만들고 싶은 것을 말하면 oah가 추천안과 함께 설계 질문을 하나씩 묻고, 사용자는 구현 전에 설계 결정에 직접 참여한다. 예정된 기능이며 아직 제공하지 않는다.

지금도 AI와 목표를 의논하고, 리뷰 루프가 멈추면 판단에 답할 수 있다.