Hanion 에이전트 작업 정책

이 정책은 Hanion에서 함께 일하는 사람과 에이전트가 작업 요청, 위임, 검수 및 승인의 경계를 일관되게 지키기 위한 기준입니다. Steve Jobs를 포함해 이 저장소에서 작업하는 모든 에이전트와 기여자는 착수 전에 이 문서를 읽고 따릅니다.

1. 적용 범위와 우선순위

이 저장소의 docs/agent-policy.md가 정책의 단일 원문이며, 사이트의 /policy는 같은 원문을 표시합니다. 정책을 바꿀 때에는 원문을 수정하고 검수합니다.
이 정책은 상위 플랫폼 지침, 보안 정책, 법적 의무, 별도의 사람 승인 요건을 대체하거나 무시할 권한을 부여하지 않습니다. 서로 충돌하면 작업을 멈추고 충돌 내용과 필요한 결정을 보고합니다.
요청을 접수하거나 담당자로 지정되었다는 사실만으로 운영 변경이나 외부 공개에 대한 권한이 생기지는 않습니다.

2. 요청 접수와 분류

Steve Jobs 등 접수 담당자는 요청자, 목적, 기대 결과, 범위, 수락 기준, 기한, 필요한 승인을 확인합니다. 빠진 핵심 정보는 질문하고, 사소한 공백은 가정으로 명시합니다.
문의·조사, 문서·디자인·코드 변경, 장애·보안 대응, 운영·배포·권한 변경 등으로 분류하고 영향과 긴급도를 기록합니다.
착수 전 기존 GitHub 이슈와 진행 중인 PR을 확인하여 중복 요청, 같은 파일이나 기능의 동시 작업, 요구사항 및 승인 범위의 충돌을 점검합니다.
중복이면 기존 이슈에 연결하고, 충돌이면 관련 담당자에게 조정을 요청합니다. 합의되지 않은 범위를 임의로 덮어쓰거나 확장하지 않습니다.

3. GitHub 이슈화

구현할 작업은 GitHub 이슈로 기록합니다. 이슈에는 목적, 범위와 범위 밖, 검증 가능한 수락 기준, 의존 관계, 가정·미정 사항, 승인 대상과 승인 상태를 적습니다.
이슈 본문과 코멘트를 작업 요구사항의 기준으로 삼습니다. 채팅에서 결정이 바뀌면 민감정보를 제거한 결정 요약과 근거를 이슈에 반영합니다.
기존 이슈에 이어서 할 수 있으면 새 이슈를 중복 생성하지 않습니다. 담당자와 상태를 명확히 기록하고 변경 사항을 추적합니다.

4. 담당과 위임

Steve Jobs 등 조정 담당자는 작업의 단일 책임자를 정하고, 전문성이 필요한 독립 작업만 적합한 에이전트에 위임합니다.
위임에는 이슈 링크, 목표, 입력 자료, 수정 가능 범위, 산출물, 수락 기준, 검증 방법과 승인 경계를 포함합니다. 위임받은 에이전트도 이 정책을 읽습니다.
구현 담당자는 기존 구조와 지침을 먼저 조사하고 최소 범위로 변경합니다. 다른 담당자의 변경을 덮어쓰지 않으며, 의존 작업과 공유 파일은 먼저 조정합니다.
위임은 승인 권한의 양도가 아닙니다. 책임자는 결과를 통합하고 미해결 사항까지 확인한 뒤 보고합니다.

5. 비밀값과 환자 식별정보

비밀번호, API 키, 토큰, 인증서 개인키 등의 비밀값과 환자 식별정보를 채팅, GitHub 이슈·코멘트, PR, 커밋, 로그 또는 공개 문서에 기록하지 않습니다.
환자 이름, 연락처, 주민등록번호, 진료기록 식별자 및 개인을 재식별할 수 있는 조합을 예시나 테스트 자료로 사용하지 않습니다. 합성 데이터나 식별 불가능한 자료만 사용합니다.
필요한 비밀값은 승인된 비밀 관리 경로로만 다루고 출력하거나 저장소에 넣지 않습니다. 노출을 발견하면 추가 복제·공유를 멈추고 민감한 원문 없이 담당자에게 사고 사실과 필요한 조치를 보고합니다.

6. 사람 승인과 실행 경계

운영 환경 변경, 배포, 외부 공개, 결제 또는 유료 자원 사용, 권한 변경, 저장소 설정·공개 범위·접근권한 변경은 실행 전에 해당 권한을 가진 사람의 명시적 승인이 필요합니다.
승인 기록에는 승인자, 대상, 범위와 조건을 남깁니다. 공개 요청은 그 요청에 명시된 콘텐츠와 대상에만 적용되며, 다른 데이터 공개나 권한 변경까지 허용하지 않습니다.
명시적으로 승인된 범위의 작업은 진행할 수 있습니다. 범위가 바뀌거나 승인이 불명확하면 해당 실행을 보류하고 필요한 결정을 요청합니다. 승인과 무관한 안전한 조사·구현·검증은 계속할 수 있습니다.
main 병합은 사람이 책임지고 수행합니다. 에이전트는 검증 결과와 PR을 제공하고 사람의 검토·병합을 기다립니다. 배포 승인은 main 병합 권한을 뜻하지 않습니다.
승인된 배포를 수행할 때에는 변경 버전, 사전 검증, 배포 결과와 복구 방법을 기록합니다. 외부 공개 전에는 비밀값과 환자 식별정보 포함 여부를 확인합니다.

7. 검수와 보고

개발 결과를 사람이 확인하는 기본 경로는 연결된 이슈와 PR의 미리보기 HTTPS URL입니다. 담당자는 링크와 확인할 화면, 합성 데이터 전용 사용법을 한국어로 안내합니다. 상세 격리·갱신·만료 기준은 저장소의 docs/preview.md를 따르며, 미리보기 승인은 운영 변경이나 main 병합 권한이 아닙니다.
구현 담당자는 프로젝트의 빌드, 타입 검사, 린트, 테스트 중 적용 가능한 검증을 실제로 실행하고 수락 기준별 근거를 남깁니다. 실행하지 못한 검증은 미실행 사실과 이유를 명시합니다.
변경은 PR로 제시하고 이슈에 연결합니다. 독립 검수자는 이슈의 수락 기준으로 변경과 검증 증거를 확인하고 PASS, FAIL 또는 BLOCKED를 판정합니다.
FAIL이면 지적 사항을 수정하고 다시 검수받습니다. 검수 통과는 사람의 승인이나 main 병합을 대체하지 않습니다.
최종 보고에는 상태, 이슈·PR 링크, 변경 요약, 수락 기준별 결과, 실행한 검증, 검수 판정, 사람이 할 일과 범위 밖 발견 사항을 포함합니다.

8. 차단과 미정 사항

요구사항 모순, 필수 정보·환경·권한 부족, 해결되지 않은 충돌은 숨기지 않고 차단 또는 질문 상태로 보고합니다. 수락 기준을 임의로 축소하거나 미완료 작업을 완료로 표시하지 않습니다.
보고에는 시도한 내용, 확인 가능한 증거, 영향 범위, 계속 진행하는 데 필요한 정보 또는 사람의 결정을 적습니다. 비밀값과 환자 식별정보는 제외합니다.
미정 사항과 가정은 이슈에 남기고 결정되면 갱신합니다. 안전하게 분리할 수 있는 작업은 계속하되, 차단된 실행을 추측으로 진행하지 않습니다.

9. 초기 제품 개발과 개발 환경

사용자에게 표시하는 한글 서비스명과 워드마크는 정확히 한의ON으로 표기합니다. hanion은 도메인·저장소·패키지 등 기술 식별자로 사용하며, 제품 화면은 별도 외부 에셋보다 텍스트 워드마크와 기존 UI 자산·시스템 글꼴을 우선 사용합니다.
초기 제품 개발에서는 앱 데이터베이스를 만들지 않습니다. 먼저 화면을 빠르게 만들고, 확인된 화면 요구에 맞춰 테이블 설계를 진행합니다.
API가 필요한 프로토타입은 실제 백엔드를 만들기보다 MockAPI 등 mock API 도구를 우선 고려합니다. 예시·검증 데이터에는 비밀값이나 환자 식별정보를 사용하지 않으며, 외부 서비스 이용에도 기존 공개·결제·승인 경계를 적용합니다.
개발 환경의 서드파티 의존성은 해당 제품의 컨테이너 이미지가 제공되면 컨테이너를 우선 사용합니다. 호스트 OS 종속성을 불필요하게 늘리지 않습니다.

10. 지속할 지침의 정책 반영

요청에 명확히 반복 가능하고 지속될 원칙이나 지침이 포함되면, 요청자가 매번 정책 기록을 별도로 명시하지 않아도 이 단일 원문에 기록합니다. 일회성 작업 지시나 가정을 지속할 원칙으로 임의 확대하지 않습니다.
접수·구현 담당자는 기존 정책과 중복·충돌 여부를 확인하고, 요청자와 근거를 이슈에 남긴 뒤 관련 정책과 프로젝트 에이전트 지침을 함께 갱신합니다. 위임 시에도 갱신된 지침을 전달합니다. 지속 여부나 적용 범위가 불명확하면 가정으로 정책을 확정하지 않고 질문·미정 사항으로 기록합니다.
정책 변경도 PR·검수·보고 절차를 따르며, 승인된 범위에서 공개 /policy가 같은 최신 원문을 표시하는지 확인합니다. 정책 기록 자체가 운영 변경·외부 공개 등의 승인이나 main 병합 권한을 추가하지 않습니다.