조직 개발 정책 전달하기

마지막 업데이트: 2026-10-28

관리자가 게시를 완료한 뒤 시작하는 다음 프롬프트에서 최신 개발 가이드를 조회해 Claude에 전달해요. 같은 대화에서도 적용되므로, 정책을 바꿀 때마다 대화를 재시작하거나 특정 skill을 부를 필요는 없어요. 초안 저장만으로는 적용되지 않아요.

무엇을 보장하고, 무엇을 보장하지 않나요?

정본은 서버에 게시된 조직 정책이에요. 로컬 POLICY.md 배포나 저장소의 다른 지침 파일을 정본으로 사용하지 않아요.

• 매 프롬프트 서버에서 최신 여부를 확인하고 현재 개발 가이드 전체를 다시 전달해요. 캐시나 직전 전달 revision 때문에 조회·전달을 생략하지 않아요.
• 정책이 철회되면 이전 정책을 대체하는 철회 상태도 전달해요. 재개·clear·compact 뒤에도 다음 프롬프트에서 다시 확인해요.
• 정책 전달은 AI의 준수나 수신 확인(ACK)을 의미하지 않아요. status의 마지막 조회·전달 revision도 모델이 읽거나 따랐다는 증거가 아니에요.
• DLP(정보 유출 방지) 기능이 아니에요. 정책 최신성을 확인하고 LLM context를 전달할 뿐, prompt의 비밀값·개인정보를 탐지·삭제하거나 외부 전송을 막지 않아요.
• 진행 중인 응답이나 tool 실행을 중단하지 않고, 기존 코드나 과거 대화 내용을 고치거나 회수하지 않아요.
• 서버 보안 강제가 아니에요. 배포 권한·승인·사용자 확인과 기존 플랫폼 검사는 그대로 필요해요. 저장소 지침과 충돌하면 임의로 한쪽을 무시하지 말고 담당자에게 확인하세요.

지원 범위

2.1.312의 host 확인은 context 전달·차단·missing CLI·timeout·재개·clear·compact 동작에 관한 것이에요. 모든 설치 조합의 end-to-end 성공이나 모델 준수, 처리 지연 실측을 뜻하지 않아요. CLI와 플러그인은 이 기능을 포함한 배포본인지 각각 도움말과 릴리스 안내로 확인하세요.

관리자: 초안을 저장하고 게시하기

조직의 설정 → 개발 정책 탭(?tab=developer-policy)에서 관리해요. 활성 조직 관리자(tenant_admin)와 플랫폼 관리자만 초안·게시·이력을 관리할 수 있어요. 설정 또는 앱 하위 관리자 권한만으로는 편집할 수 없어요. 일반 구성원은 현재 게시본만 읽을 수 있어요.

1. 대상 조직과 공개 범위를 확인하세요. 조직당 하나의 정책이 있고 앱별 상속은 없어요.
2. 개발 가이드와 배포 안내를 작성하세요. 두 구역은 각각 최대 4096 UTF-8 bytes예요. 글자 수가 아니므로 한글·이모지는 더 많은 bytes를 사용해요. 한 구역만 비워 둘 수 있어요.
3. 편집/미리보기를 전환해 내용을 확인하고 초안 저장을 누르세요. 일반 설정 저장과 별개예요. 초안은 아직 구성원이나 AI에 전달되지 않아요.
4. 게시 창에서 저장된 본문을 다시 확인하세요. 정책이 사용자가 연결한 AI 서비스에 전달될 수 있다는 확인란을 게시할 때마다 선택해야 해요. 이는 특정 AI 제공자의 승인이나 실제 전달 ACK가 아니에요. 비밀값·개인정보를 넣지 마세요.
5. 게시가 완료되면 새 revision이 생겨요. 이후 시작하는 연결 프로젝트의 다음 프롬프트에 개발 가이드가 전달돼요. 배포 안내는 배포 준비 단계에서 별도로 읽어요.

미리보기·게시 창·이력은 안전한 Markdown으로 표시해요. raw HTML이나 위험한 링크 scheme을 실행하지 않고 외부 이미지를 자동으로 가져오지 않아요.

철회하려면 두 구역을 모두 정확히 빈 문자열로 지우고 초안 저장 후 게시하세요. 공백만 남겨 두는 것은 철회가 아니에요. 철회도 AI 전달 확인이 필요하고 새 양수 revision으로 이력에 남아요. 이력을 삭제하지 않아요. 한 번도 게시하지 않은 상태는 unset(revision 0), 게시된 상태는 published, 철회는 withdrawn이에요.

다른 관리자가 먼저 바꿨다면 충돌(409)을 확인하고 내 편집과 서버 초안을 비교해 수동 반영하세요. 로컬 입력을 버리거나 무조건 덮어쓰지 마세요. 같은 내용을 다시 게시할 때도 최신 게시 revision을 기준으로 초안을 다시 저장해야 해요.

저장·게시 응답이 끊겼다면 실패라고 단정하거나 바로 재시도하지 마세요. 서버 초안·현재 게시본·해당 초안의 게시 이력을 재확인해요. 다른 관리자의 후속 변경으로 확인할 수 없다면 결과는 미확정으로 남을 수 있어요. 게시 이력은 최신 revision부터 확인할 수 있어요.

첫 401 응답을 받으면 로컬 입력을 보존한 채 정책 편집기를 잠그며 인증을 자동 refresh하지 않아요. 차단된 편집기 밖에서 로그인을 복구한 뒤 돌아와 서버 초안과 비교하고 다시 저장하세요.

기존 비공개 배포 심사 지침(review-guidelines)과 플러그인의 POLICY.md는 별개예요. 기존 내용을 자동으로 공개하거나 이관하지 않아요.

구성원: 프로젝트 연결하기

터미널에서 아래 명령의 UUID와 경로를 실제 조직·프로젝트 값으로 바꾸세요.

axhub tenants developer-policy get --tenant <uuid> --json
axhub tenants developer-policy bind --tenant <uuid> --project <path>
axhub tenants developer-policy status --json
axhub tenants developer-policy unbind --project <path>

• get은 인증된 현재 서버 조회예요. hook 적용 시험이나 AI 전달 증거가 아니에요. Codex에서도 이 방법으로 수동 조회할 수 있어요.
• bind는 조직 접근을 확인한 뒤 로컬 .axhub/state/developer-policy.json에 origin·tenant·schema를 저장해요. credential은 넣지 않아요. 다른 연결을 교체하려면 의도한 조직인지 확인한 뒤 --force를 명시하세요.
• 가장 가까운 명시적 연결을 사용하되 Git 저장소·worktree 경계를 넘지 않아요. worktree마다 따로 연결하세요. 앱 이름·slug가 있는 manifest나 이전 조직 선택 캐시는 연결 증거가 아니에요.
• 서버 목적지는 신뢰한 CLI profile/endpoint에서 정해요. 연결 파일의 origin은 일치 확인용이며, 이를 편집해 다른 서버로 인증 정보를 보내게 할 수 없어요.
• status는 서버에 접속하지 않는 로컬 진단으로 profile·binding source 표시(절대 경로 아님)·비활성화 원인·capability·마지막 조회·전달 revision을 구분해요. AI delivery ACK는 제공하지 않아요.
• bind·unbind·status의 --project는 생략하면 현재 디렉터리예요. 다른 프로젝트 상태는 axhub tenants developer-policy status --project <path> --json으로 확인하세요.
• unbind는 로컬 연결만 해제하며 조직의 서버 게시본을 철회하지 않아요. 읽을 수 없거나 손상된 연결은 미연결로 숨기지 않고 차단해요.

자동 동기화 끄기

다음 둘 중 하나라도 해당하면 자동 동기화가 꺼져요(OR 조건).

• host 프로세스 환경의 AXHUB_NO_POLICY_SYNC 값이 정확히 1.
• ~/.axhub/config/no-policy-sync 파일이 존재함.

status에서 모든 비활성화 원인을 확인하세요. 다시 켜려면 환경변수 조건과 파일 조건을 모두 해제하고 host가 변경된 환경을 사용하도록 해야 해요. 비활성화하거나 연결을 해제하면 다음 프롬프트 자동 반영 보장도 없어져요.

명시적 get과 배포 준비의 정책 조회는 계속 동작해요. 자동 hook만 끄는 설정이며 서버 권한이나 배포 검사를 우회하지 않아요. CLI가 없으면 wrapper의 실행 디렉터리가 확실히 미연결일 때만 건너뛰어요. 구 CLI의 최종 사용법 오류(exit 64)도 실행 디렉터리가 확실히 미연결일 때만 조용히 건너뛰고, 연결된 경우 UNSUPPORTED로 차단해요. 구 CLI는 다른 host payload cwd를 검증할 수 없어요. 모든 미연결 오류를 허용하는 규칙은 아니에요. 지원 helper는 실행 디렉터리가 미연결이어도 payload cwd를 검증하며 다른 오류나 불확실한 binding은 차단해요.

배포 안내

배포 준비에서는 실제 대상 앱의 조직을 확인하고 최신 deployment_markdown을 인증된 CLI로 읽어요. 읽기에 실패하면 클라이언트 준비를 중단해요. unset 또는 withdrawn이면 정상 진행해요. 구 서버의 미지원 API 오류를 정책 없음으로 처리하지 않아요.

배포 안내를 자연어로 점검하는 것은 서버 강제 규칙이 아니에요. 기존 플랫폼 context, 배포 승인·권한 검사·사용자의 배포 확인은 유지돼요. 개발 프롬프트에는 개발 가이드만 전달하며 배포 안내를 매번 함께 넣지 않아요.

차단 후 복구

차단은 대기열이나 자동 재개가 아니에요. 채팅 밖 터미널에서 복구 → 같은 환경의 명시적 조회 확인 → 사용자가 프롬프트 수동 재전송 순서로 진행하세요. host가 입력을 자동 보존하거나 복원한다고 약속하지 않아요.

일반 네트워크 실패와 429는 자동 재시도하지 않아요. OAuth refresh는 최대 1회, 사용할 캐시 없는 304의 복구 GET은 최대 1회이며 같은 deadline 안에서만 수행해요. wrapper 전체 2초는 실패 처리 한도이지 실측 응답 속도나 항상 2초 안에 정책을 가져온다는 SLA가 아니에요.

POLICY_AUTH_REQUIRED — 인증 복구

hook은 로그인 창이나 keychain 승인창을 열지 않아요. 먼저 host와 터미널의 profile·endpoint·credential backend가 같은지 확인하세요. 터미널에서 axhub auth login --force로 로그인하더라도 keychain에만 저장된 로그인 성공은 파일 기반 비대화형 hook 인증 성공이 아니에요.

profile 기반 파일 인증을 선택한다면 같은 profile·endpoint를 유지해 axhub --no-keychain auth login --force로 로그인하세요. 이는 credential을 OS keychain 대신 파일에 저장하는 변경이에요. 저장 위치와 파일 권한을 확인하고 파일·토큰 내용을 채팅이나 로그에 붙이지 마세요. host가 명시적 --token-file을 사용한다면 바로 그 파일을 복구해야 하며 profile 저장소 로그인이 그 파일을 갱신한다고 가정하면 안 돼요. CLI 전역 인증 옵션을 참고하세요. 로그인 후 같은 비대화형 환경에서 get을 확인하고 프롬프트를 다시 보내세요.

명시적 token 파일은 그 파일을 발급한 원래 절차로 갱신·교체하세요. CLI에 별도 token-export 명령이 있다고 가정하지 마세요. 파일 지정 해제나 profile 저장소로 전환하는 것은 인증 출처를 바꾸는 선택이므로 사용자가 의도한 경우에만 진행하세요.

ACCESS_DENIED — 조직 권한

연결된 조직과 현재 로그인한 사용자를 확인하고 관리자에게 멤버십을 확인받으세요. 권한 회수는 캐시가 있어도 우회하지 못해요. 다른 조직을 의도했다면 명시적으로 다시 연결하세요.

BINDING_CONFLICT — 연결 불일치

로컬 status에서 binding source 표시와 신뢰한 profile을 확인하고 endpoint 설정은 별도로 확인하세요. source 표시는 파일의 절대 경로가 아니에요. origin·조직 불일치나 손상된 파일을 임의 서버 주소로 고치지 마세요. 의도한 대상에 bind하고 다른 연결 교체에만 --force를 쓰세요.

NETWORK — 연결 실패

서버 접속·VPN·네트워크를 복구하고 명시적 get으로 확인하세요. 오래된 캐시로 진행하거나 반복 자동 재시도하지 않아요.

DEADLINE — 확인 시간 초과

네트워크와 비대화형 인증 저장소 접근을 확인하세요. 느린 조회가 끝날 때까지 해당 프롬프트를 자동으로 붙잡아 두거나 재개하지 않아요.

CACHE_UNUSABLE — 캐시 사용 불가

CLI가 안내한 로컬 저장 위치의 접근 권한과 디스크 상태를 확인하세요. 정책 본문이나 credential을 수동으로 캐시에 복사하지 말고 서버 재조회로 복구하세요.

UNSUPPORTED — 지원 조합 아님

정책 기능을 포함한 서버·CLI·플러그인과 지원 host 조합을 확인하세요. 구 CLI의 사용법 오류(64)나 구 서버의 404는 정책 없음이 아니에요. Codex는 수동 조회만 지원해요.

PROTOCOL — 응답 형식 오류

지원되는 CLI·플러그인 조합으로 맞추세요. helper는 정확히 하나의 JSON을 반환해야 하며 추가 stdout·잘못된 JSON을 성공으로 처리하지 않아요. raw 응답·정책 본문 대신 정제된 오류 코드로 문의하세요.

INTERNAL — 내부 오류

정제된 오류 코드와 CLI·플러그인·host 버전을 지원 담당자에게 전달하세요. 선택적 error.context에는 확인·검증된 profile·tenant_id·고정 binding_source(project:.axhub/state/developer-policy.json)와 서버 X-Request-ID에서 실제 받은 request_id만 들어가며 모르는 값은 생략해요. adapter는 raw upstream 문구 대신 고정 복구 문구와 이 안전한 진단을 표시해요. 이 정보만 복사하고 정책 본문·prompt·raw 응답·절대 경로·토큰·credential URL은 보내지 마세요. 이 진단은 host 전달 ACK가 아니에요.

RATE_LIMITED — 요청 제한

서버가 안내한 제한이 해제될 때까지 기다린 뒤 명시적으로 다시 조회하세요. 자동 재시도 폭주를 만들지 말고 복구 후 프롬프트를 직접 다시 보내세요.