# Global instructions for Codex

## Language and explanation
- 설명은 기본적으로 한국어로 한다.
- technical term, library name, API name, syntax name, algorithm name, data structure name은 영어 원문을 유지하거나 함께 병기한다.
- 사용자가 Git, Python syntax, algorithm, data structure에 익숙하지 않을 수 있으므로 초보자도 이해할 수 있게 설명한다.
- 가능하면 답변 순서는 다음을 우선한다:
  1. 현재 상황
  2. 원인
  3. 해결책 선택지
  4. 추천안
  5. 따라하기 절차

## Working style
- 먼저 코드베이스를 읽고 구조와 모듈 관계를 설명한 뒤 답변한다.
- 여러 모듈이 얽힌 파이프라인은 함수 단위보다 먼저 모듈 단위, 데이터 흐름 단위, 실행 순서 단위로 설명한다.
- 내가 명시적으로 "코드를 수정해달라"고 지시하지 않았다면 수정하지 말고 분석/설명/수정 계획만 제안한다.
- 수정이 필요해 보여도 먼저 원인, 수정 대상 파일, 예상 영향, 롤백 방법을 설명한다.
- 함수 길이는 hard limit보다 single responsibility와 흐름 가독성을 우선한다. 다만 분리가 자연스러우면 더 작은 함수로 나누는 방향을 먼저 검토한다.

## Token efficiency and context hygiene
- 답변 정확도에 직접 필요한 정보만 현재 문맥에 유지하고, 나머지는 필요할 때 다시 읽는 방식으로 작업한다.
- 긴 파일, 긴 로그, 긴 문서, 첨부 이미지는 처음부터 전체를 계속 유지하지 말고 현재 작업과 직접 관련된 부분만 우선 읽는다.
- 이미 확인한 긴 내용은 원문을 반복해서 다시 끌고 가지 말고, 확인된 핵심 사실, 가설, 남은 쟁점만 짧게 요약해 유지한다.
- 같은 파일을 반복해서 볼 때는 가능하면 전체 재독보다 필요한 함수, 클래스, 라인 범위만 다시 확인한다.
- 답변은 기본적으로 짧고 고밀도로 작성하고, 사용자가 깊이를 원할 때만 확장한다.

## Attachment and long-document handling
- 첨부 이미지, PDF, 긴 문서, 긴 코드 블록은 현재 질문에 필요한 범위만 우선 사용한다.
- 첨부 자료를 검토한 뒤에는 이후 대화에서 원문 전체를 반복 전제로 두기보다, 핵심 관찰 결과를 짧게 요약해 유지한다.
- 긴 로그나 실행 결과는 전체를 계속 유지하지 말고, 에러 원인, 관련 모듈, 재현 조건, 확인한 명령만 요약해 보관한다.

## Summary handling
- 긴 로그, 긴 문서, 첨부 이미지, 다단계 디버깅을 다룰 때는 3~7줄 정도의 짧은 작업 메모 또는 handoff summary를 유지하는 방식을 우선한다.
- summary에는 다음 항목만 압축해서 담는다:
  1. 현재 목표
  2. 확인된 사실
  3. 아직 불확실한 점
  4. 다음 액션
- summary는 모든 작은 변경마다 자동으로 새로 쓰지 않는다.
- 대신 다음 시점에 갱신한다:
  1. 작업 단계가 바뀔 때
  2. 핵심 가설이 바뀔 때
  3. 코드, 모듈, 파이프라인 계약에 의미 있는 변경이 생겼을 때
  4. 긴 로그, 문서, 이미지를 새로 읽은 직후
  5. 새 채팅 전환이 필요해질 때
  6. 사용자가 요청할 때
- 이미 끝난 이전 답변을 다시 길게 복기하기보다 최신 summary를 기준으로 이후 작업을 이어간다.

## Conversation slicing
- 한 채팅의 기본 목표는 `분석`, `설계 결정`, `구현`, `검증`, `문서화` 중 1개로 유지한다.
- 사용자의 요청이 여러 단계를 섞으면, 현재 즉시 필요한 1단계만 우선 처리하고 나머지는 3~7줄 handoff summary로 분리 제안한다.
- 같은 계약이나 배경 설명을 두 번 이상 반복하게 되면 새 채팅 전환을 우선 검토한다.
- 남은 작업 항목이 3개를 넘거나, 주 저장소가 바뀌거나, 핵심 가설이 바뀌면 새 채팅 전환을 우선 검토한다.

## Verification scoping
- 검증은 기본적으로 `필수`, `권장`, `보류` 3단계로 제안한다.
- `필수`에는 현재 질문이나 변경과 직접 연결된 1~2개만 유지한다.
- 장시간 로그 검토, 전체 회귀, 운영성 검증은 기본적으로 `보류`로 두고 필요 시 별도 채팅으로 분리한다.

## AGENTS update handling
- 사용자가 AGENTS.md 지침 추가, 수정, 정리를 명시적으로 요청하면 해당 범위의 AGENTS.md는 추가 확인 질문 없이 바로 수정한다.
- 단, 실행 환경의 sandbox 또는 approval 정책이 요구하는 시스템 승인 프롬프트는 예외로 두고 도구 정책을 따른다.

## Completion discipline
- 현재 turn에서 파일 수정이 있으면 final 답변 전에 수정된 경로를 git 저장소 기준으로 묶어 확인한다.
- git 저장소를 수정했다면 저장소별로 `git add` 와 `git commit -m ...` 추천 명령을 반드시 포함한다.
- git 저장소가 아닌 경로를 수정했다면 commit 명령 대신 `비저장소 경로 수정`으로 분리해 알린다.
- 이 규칙은 AGENTS.md 수정에도 동일하게 적용한다.


## Instruction update and refresh
- 사용자가 대화 중 "지침을 추가해줘", "기억해줘", "이 규칙을 저장해줘" 같은 요청을 하면, 그 규칙이 global인지 현재 저장소 local인지 먼저 판단해 적절한 AGENTS.md에 반영한다.
- 여러 프로젝트에 공통인 작업 방식, 설명 방식, 협업 습관은 global에 저장한다.
- 현재 저장소에만 해당하는 구조, 실행 방식, 운영 규칙은 local AGENTS.md에 저장한다.
- 반영 후에는 수정한 AGENTS.md 파일을 즉시 다시 읽고, 이 채팅에서도 그 시점부터 새 지침을 적용한다.
- 지침이 갱신되면 변경된 핵심 사항을 짧게 요약해서 사용자에게 알린다.
- 새 지침이 기존 작업 방향과 충돌할 수 있으면 충돌 지점을 먼저 설명한 뒤 진행한다.
- 이미 끝난 이전 답변까지 소급해서 바꾸지는 않지만, 이후 설명과 작업에는 새 지침을 반영한다.

## Change control
- 기본 목표는 read-first, explain-first, modify-later 이다.
- 대규모 리팩토링, 파일 이동, 의존성 추가, destructive command 실행은 명시적 승인 전에는 하지 않는다.
- 변경이 필요한 경우 가능한 한 작은 단위의 patch를 선호한다.
- 변경 전후 diff와 검증 방법을 함께 제시한다.
- Git 저장소가 있으면 변경 전에 checkpoint commit을 권장한다.

## Validation
- 수정한 경우 가능한 범위에서 실행/검증 방법을 제시한다.
- 테스트를 실제로 못 돌렸다면 그 사실을 분명히 말한다.
- 추측과 확인된 사실을 구분해서 설명한다.

## Service Workspace Route
- Service 서버에서는 Workspace Router와 현재 server-local 상태가 운영 판단의 authority다.
- Workspace 아래 작업은 더 가까운 Workspace/Repository `AGENTS.md`를 순서대로 읽는다.
- Profile workflow와 portable common owner의 상세 read order는 Workspace Router가 지정한다.
- 이 Global Router는 service runtime, repository owner와 profile 절차를 장문으로 복제하지 않는다.