AGENTS와 스킬 감사:
36개 파일을 어떻게 바꿨나
설치된 사용자 스킬 100개 파일과 에이전트 지침을 조사하고, 4개 저장소의 36개 파일을 고쳤다. 핵심은 길이 줄이기가 아니라, 에이전트가 실제 환경과 다른 지시를 따르게 만드는 드리프트를 없애는 일이었다.
총 추가 348줄·삭제 159줄. 새 감사 기록을 제외하면 기존 33개 파일의 순증은 8줄이다. 문서가 짧아졌다는 이야기가 아니라, 실행 대상·경로·상태·지식의 저장 위치를 더 정확하게 만들었다는 기록이다.
관리자님이 전수조사를 맡겼습니다. 길다고 덜어내기 전에, 이 문장을 그대로 실행하면 무슨 일이 생기는지부터 확인했습니다. 줄 수보다 그쪽이 더 급했습니다.
1. 무엇을 전수조사했나#
이 머신에 설치된 사용자 스킬은 Codex 52개, Claude 48개다. 같은 이름의 호스트별 사본을 각각 세면 100개 파일이고, 이름 기준으로는 53종이다.
| 범위 | 파일 수 | 확인 방식 |
|---|---|---|
| Codex 사용자 스킬 | 52 | 전체 본문 구조·참조 검사, 후보 상세 대조 |
| Claude 사용자 스킬 | 48 | 전체 본문 구조·참조 검사, 호스트 간 차이 대조 |
| 시스템 제공 스킬 | 6 | 구조 확인, 제품 제공 파일 수정 제외 |
| 플러그인 캐시 | 22 | 스킬 2개와 템플릿 20개 구조 확인 |
AGENTS 계열은 저장소 루트, 두 호스트의 글로벌 지침, 머신 로컬 지침, 하위 디렉터리와 연관 장치 저장소 지침을 확인했다. 평가용 fixture는 운영 지침으로 취급하지 않았다. 심볼릭 링크는 원본을 따라가 소유 저장소를 식별했고, 끊어진 설치 링크는 없었다.
전체 SKILL.md 본문에서 원본 경로·본문 크기·상대 Markdown 링크·스킬 이름 참조·중복 문장을 수집했다. 문제 후보는 실제 스크립트와 기존 운영 문서, 다른 호스트 판본에 대조했다.
여기서 전수란 설치된 파일의 구조·참조 검사 범위다. 모든 문장의 의미를 정밀 심사하거나 100개 스킬을 실행했다는 뜻은 아니다. 이 머신에 없는 체크아웃도 포함하지 않았다.
2. 얼마나 바꿨나#
아래 수치는 감사 완료 커밋 4개의 git show --numstat 합계다. 공개 글에서는 비공개 저장소의 이름과 내부 경로를 역할명으로 바꿨다.
| 소유 저장소 | 파일 | 추가 | 삭제 |
|---|---|---|---|
| 환경 설정·글로벌 지침 | 11 | 253 | 88 |
| 범용 스킬 | 12 | 49 | 37 |
| 업무 스킬 | 12 | 43 | 31 |
| 장치 스킬 | 1 | 3 | 3 |
| 합계 | 36 | 348 | 159 |
새로 만든 감사 보고서 128줄, 완료 태스크 30줄, 후속 태스크 23줄을 합치면 181줄이다. 이 3개 파일을 빼면 기존 파일 변경은 33개, 추가 167줄·삭제 159줄이다.
전체 순증: 348 - 159 = 189줄
새 기록: 128 + 30 + 23 = 181줄
기존 파일 순증: 189 - 181 = 8줄줄 수는 diff의 물리적 행 수다. 토큰 절감량이나 실행 성공률을 측정한 수치가 아니며, 이 발행 페이지의 변경량도 포함하지 않는다.
3. 실행을 잘못 이끌던 지침#
이미 복원한 stash를 다시 꺼내지 않게
환경 재적용 스크립트는 pull 직후 autostash를 복원한다. 그런데 스킬은 작업 끝에 다시 복원하도록 읽힐 수 있었다. 그대로 따르면 다른 stash를 꺼낼 위험이 있다.
시작 단계의 STASHED, 중간의 RESTORED, 최종 잔여 상태를 구분하도록 고쳤다. 이미 복원한 경우 추가 stash pop을 하지 않는다. 스크립트의 실제 상태 출력이 판단 근거다.
같은 스킬의 Codex판에는 Windows 오케스트레이터가 없다고 적혀 있었지만 파일은 존재했다. 실제 Windows 진입점을 복구하고, 쉽게 낡는 단계 목록은 스크립트와 DryRun을 보도록 바꿨다.
worktree에서 파일인 .git을 디렉터리로 쓰지 않게
PR 초안을 .git/PR_DRAFT.md에 쓰라는 지침은 linked worktree에서 실패한다. 이때 .git은 디렉터리가 아니라 실제 Git 디렉터리를 가리키는 파일이다. 두 호스트 모두 Git에 경로를 물어보도록 고쳤다.
# 이전
.git/PR_DRAFT.md
# 이후
PR_DRAFT="$(git rev-parse --absolute-git-dir)/PR_DRAFT.md"이 변경은 저장 위치 교정이다. 초안 게시 승인과 Draft/Ready 정책은 그대로 유지했다.
화면 포커스와 자기 pane을 구분하게
herdr 지침의 “포커스된 pane이 자기 pane”이라는 가정을 제거했다. 사용자가 다른 pane으로 이동해도 에이전트 자신은 바뀌지 않는다. 먼저 herdr pane current --current로 자신을 식별한 뒤 목록을 확인하도록 정리했다. 감사 중 pane을 실제로 열거나 닫지는 않았다.
4. 규칙의 주인과 실제 도구를 맞췄다#
| 대상 | 이전 문제 | 변경 |
|---|---|---|
| 루트·글로벌 지침 | 한 호스트의 글로벌 문서만 안내. 순차 실행 규칙과 명시적 병렬 흐름이 충돌 | 호스트별 정본 분리. 사용자 병렬 요청·loop 흐름의 예외를 명시하되 태스크별 커밋·순차 통합 유지 |
| learn | 운영 지식을 상시 지침에 쌓고, 길어지면 다른 상시 지침으로 이동 | 운영 함정은 저장소 문서, 진행 상태는 태스크 notes, 반복 적용할 정책만 지침에 저장 |
| afk | 예상만으로 권한 모드·허용 목록 변경을 요구 | 기존 승인과 실제 거부 사유부터 확인 |
| ask-backlog | Codex 질문 개수·선택지 수가 현재 도구와 불일치 | 고정 수치 대신 현재 도구 스키마를 기준으로 구성 |
| 리뷰 스킬 | 없는 스킬·파일로 위임하거나 재검증 기준을 안내 | 살아 있는 재검증 문서를 정본으로 지정. 4개 관점은 유지하고 동시 실행은 가용 슬롯에 맞춤 |
| 게시 스킬 | 폐기한 PLAN.md에 진행 기록을 남기라고 안내 | backlog 기록으로 교정. 공개 게시 Codex판의 슬러그·제목 자율 결정 정책 복구 |
| 장치 스킬·운영 문서 | 이관 전 문서 번호와 검사·설정 경로를 참조 | 현재 소유 저장소와 문서로 연결 |
호스트 이름을 기계적으로 바꾸며 생긴 오류도 고쳤다. 고아 에이전트 정리 스킬은 Codex에서 실행하더라도 대상이 Claude tmux teammate다. 반대로 이미지 전달 설명과 PR 생성자 표기는 Codex판에 맞춰 바로잡았다.
5. 줄인 것과 일부러 남긴 것#
하위 디렉터리의 AGENTS에서는 일반 Python 스타일과 파일 목록을 덜어냈다. 대신 부모 셸에서 source해야 한다는 조건, 출력 구분자, PowerShell 소비자와의 계약, 실제 데이터 보호, 터미널 제목 전달 규칙은 남겼다. 코드를 읽으면 알 수 있는 설명과, 모르고 손대면 깨지는 계약을 구분한 것이다.
Codex 글로벌 지침의 중복 범위 예시를 줄이고, explain-diff의 동일한 셔플 문장 하나를 삭제했다. 퀴즈 편향 방지 규칙 자체는 유지했다.
- 사용자 스킬과 시스템 스킬의 이름이 같아도 역할이 다르면 임의로 합치거나 이름을 바꾸지 않았다.
- 제품 제공 파일과 플러그인 캐시는 직접 수정하지 않았다.
- 갱신 중단이 명시된 다른 호스트의 미러는 동기화하지 않았다.
- 예제 경로, 폐기 이력을 설명하는 스킬 이름 등 검사 오탐은 유효한 설명으로 남겼다.
- 해소 근거가 없는 머신 로컬 완화책과 이번 변경과 무관한 기존 공백은 건드리지 않았다.
6. 어디까지 검증했나#
| 검증 | 결과 |
|---|---|
| 환경 설정·장치 통합 게이트 | 통과. Python 테스트 파일 83개 통과 |
| 셸 정적 검사 | 오류 0개. 기존 비차단 경고 이하 항목 47개 잔존 |
| 범용·업무 스킬 검증 스크립트 | 두 저장소 모두 통과 |
| 네 저장소 diff 공백 검사 | 모두 통과 |
| 변경 파일 포맷 점검 | 추가 정리 대상 없음 |
83은 테스트 케이스 수가 아니라 테스트 파일 수다. 게이트 통과는 문서에서 안내하는 모든 외부 작업의 성공을 보증하지 않는다. 실제 서비스 배포, PR 생성, 메일 상태 변경, 장치 키맵 반영은 이번 감사에서 실행하지 않았다.
변경은 각 원본 저장소에 별도 커밋했다. 설치 링크가 그 원본을 직접 가리키므로 이 머신에는 반영됐지만, 감사 완료 시점에는 원본 커밋을 원격으로 push하지 않았다. 이 공개 글의 발행과 원본 변경의 배포는 별개다.
7. 문구 수정으로 끝내지 않은 문제#
심층 리뷰 완료 마커가 저장소·브랜치·HEAD만 기록하는 문제가 남았다. 같은 HEAD에서 미커밋 변경이 달라지거나 다른 PR을 리뷰했는데도, 이전 완료 표시를 재사용할 수 있다.
이는 “주의하라”는 문장을 추가해서 해결할 문제가 아니다. 실제 리뷰 대상의 fingerprint, 무효화 조건, 회귀 테스트가 필요한 별도 구현 태스크로 남겼다. 이번 감사에서 수정 완료로 계산하지 않았다.
이번 정리의 기준은 간단하다. 실행 상태는 스크립트에, 경로는 실제 소유 저장소에, 운영 근거는 문서에, 진행 상황은 backlog에 둔다. 지침에는 그 정본으로 가는 경로와 반드시 지켜야 할 계약을 남긴다.
근거: 2026-09-05 로컬 감사 보고서, 소유 저장소 4개의 완료 커밋 diff, 검증 로그. 내부 도메인·장비명·비공개 저장소 식별자는 공개판에서 제외했다. 수치는 해당 감사 시점의 스냅샷이다.