스킬 여덟 개의 절차가 SKILL.md(합계 약 1,560줄)에 적혀 있고, 에이전트는 그 안의 코드 블록 32개(bash 22개)를 읽고 직접 따라 한다. 같은 일을 하는 스크립트가 이미 있는데도 문서가 절차를 따로 들고 있는 경우가 있다.
resume: resume_session.sh 가 전체 흐름(ID 해석, fresh-spawn 폴백, 기동, 시작 다이얼로그, YAML 갱신)을 하는데, SKILL.md 의 Workflow 는 같은 흐름을 36줄 bash 로 다시 적어 에이전트가 손으로 실행하게 한다. 둘 중 하나가 바뀌면 다른 쪽은 조용히 어긋난다.
stop / status / create: pre-flight 와 검증 단계가 인라인 python3 -c / bash 조각으로 문서에 있다.
문서가 절차를 들고 있으면 (1) 에이전트마다 해석이 달라 같은 스킬이 다르게 실행되고, (2) 테스트가 문서 속 절차를 검증하지 못하며, (3) 모델이 바뀌거나 문맥이 요약될 때 단계가 빠진다. PR #41 리뷰에서 반복된 "bash 에 들어간 판정" 문제(#17 합의 D)와 #26 의 이중 로더도 같은 뿌리다.
원칙
고정된 워크플로우(순서·분기·판정이 정해진 절차)는 Python 진입점 하나로 둔다. 스킬마다 python -m lib_py.<skill> <subcommand> 형태의 명령 하나가 전체 흐름을 수행하고, 결과를 종료 코드와 한 줄 요약(필요하면 --json)으로 돌려준다.
bash 는 외부 프로세스를 만지는 얇은 층만 남긴다 (#17 경계 규칙: "결정을 내리는 코드는 Python, 외부 프로세스를 만지는 코드는 bash. 애매하면 Python").
SKILL.md 는 최소 지침만 남긴다: 언제 쓰는가, 호출할 명령 한 줄과 옵션 표, 종료 코드 표, 사람이 판단해야 하는 지점(예: --purge-conversation 확인), 함정. 절차를 재현하는 코드 블록은 두지 않는다.
범위(단계)
목록화: 스킬별로 SKILL.md 의 코드 블록을 (a) 이미 스크립트가 하는 일의 중복, (b) 스크립트에 없는 절차, (c) 순수 설명 예시로 나눈다.
중복 제거부터: (a) 는 문서에서 지우고 해당 진입점 호출 한 줄로 바꾼다. resume 이 첫 대상.
빠진 절차의 코드화: (b) 는 Python 진입점의 서브커맨드로 옮기고 테스트를 붙인다.
진입점 정리: bash 진입 스크립트는 Python 진입점을 부르는 얇은 래퍼로 줄인다. 판정 로직의 이전은 #17 항목 4 와 겹치므로 그 목록을 따른다.
문서 가드: SKILL.md 에 실행용 코드 블록이 다시 늘지 않도록, 허용된 블록(호출 예시 한 줄 등) 외에는 실패하는 테스트를 둔다.
완료 조건
여덟 스킬 각각이 진입 명령 하나로 전체 흐름을 수행하고, SKILL.md 는 그 명령을 부르는 지침만 담는다.
문서에 있던 각 절차 단계가 Python 테스트로 검증된다.
.claude/skills 심볼릭 링크와 에이전트별 스킬 로딩 경로가 그대로 동작한다.
관계
#17 항목 4(래퍼 종결 처리의 Python 이전)와 판정 로직 이전 목록을 공유한다. 이 이슈는 "문서 → 코드" 방향, 항목 4 는 "bash → Python" 방향이다.
#26(.mam.env 이중 로더)은 이 원칙의 작은 첫 사례다.
#40(세션 ID 자동 확정)은 새 진입점의 resume/stop 흐름 위에 얹는다.
비범위
스킬의 동작 변경. 이 작업은 같은 동작을 문서에서 코드로 옮기는 것이다.
bash 전면 재작성. 외부 프로세스 호출(herdr, 에이전트 CLI, git)은 bash 에 남아도 된다.
## 배경
스킬 여덟 개의 절차가 SKILL.md(합계 약 1,560줄)에 적혀 있고, 에이전트는 그 안의 코드 블록 32개(bash 22개)를 읽고 직접 따라 한다. 같은 일을 하는 스크립트가 이미 있는데도 문서가 절차를 따로 들고 있는 경우가 있다.
- **resume**: `resume_session.sh` 가 전체 흐름(ID 해석, fresh-spawn 폴백, 기동, 시작 다이얼로그, YAML 갱신)을 하는데, SKILL.md 의 Workflow 는 같은 흐름을 36줄 bash 로 다시 적어 에이전트가 손으로 실행하게 한다. 둘 중 하나가 바뀌면 다른 쪽은 조용히 어긋난다.
- **stop / status / create**: pre-flight 와 검증 단계가 인라인 `python3 -c` / bash 조각으로 문서에 있다.
- 규모: 셸 계층(lib.sh 3,083줄 + 스킬 진입 스크립트 6,529줄) 대 Python 코어(lib_py 11,381줄).
문서가 절차를 들고 있으면 (1) 에이전트마다 해석이 달라 같은 스킬이 다르게 실행되고, (2) 테스트가 문서 속 절차를 검증하지 못하며, (3) 모델이 바뀌거나 문맥이 요약될 때 단계가 빠진다. PR #41 리뷰에서 반복된 "bash 에 들어간 판정" 문제(#17 합의 D)와 #26 의 이중 로더도 같은 뿌리다.
## 원칙
- **고정된 워크플로우(순서·분기·판정이 정해진 절차)는 Python 진입점 하나로 둔다.** 스킬마다 `python -m lib_py.<skill> <subcommand>` 형태의 명령 하나가 전체 흐름을 수행하고, 결과를 종료 코드와 한 줄 요약(필요하면 `--json`)으로 돌려준다.
- **bash 는 외부 프로세스를 만지는 얇은 층만 남긴다** (#17 경계 규칙: "결정을 내리는 코드는 Python, 외부 프로세스를 만지는 코드는 bash. 애매하면 Python").
- **SKILL.md 는 최소 지침만 남긴다**: 언제 쓰는가, 호출할 명령 한 줄과 옵션 표, 종료 코드 표, 사람이 판단해야 하는 지점(예: `--purge-conversation` 확인), 함정. 절차를 재현하는 코드 블록은 두지 않는다.
## 범위(단계)
1. **목록화**: 스킬별로 SKILL.md 의 코드 블록을 (a) 이미 스크립트가 하는 일의 중복, (b) 스크립트에 없는 절차, (c) 순수 설명 예시로 나눈다.
2. **중복 제거부터**: (a) 는 문서에서 지우고 해당 진입점 호출 한 줄로 바꾼다. resume 이 첫 대상.
3. **빠진 절차의 코드화**: (b) 는 Python 진입점의 서브커맨드로 옮기고 테스트를 붙인다.
4. **진입점 정리**: bash 진입 스크립트는 Python 진입점을 부르는 얇은 래퍼로 줄인다. 판정 로직의 이전은 #17 항목 4 와 겹치므로 그 목록을 따른다.
5. **문서 가드**: SKILL.md 에 실행용 코드 블록이 다시 늘지 않도록, 허용된 블록(호출 예시 한 줄 등) 외에는 실패하는 테스트를 둔다.
## 완료 조건
- 여덟 스킬 각각이 진입 명령 하나로 전체 흐름을 수행하고, SKILL.md 는 그 명령을 부르는 지침만 담는다.
- 문서에 있던 각 절차 단계가 Python 테스트로 검증된다.
- `.claude/skills` 심볼릭 링크와 에이전트별 스킬 로딩 경로가 그대로 동작한다.
## 관계
- #17 항목 4(래퍼 종결 처리의 Python 이전)와 판정 로직 이전 목록을 공유한다. 이 이슈는 "문서 → 코드" 방향, 항목 4 는 "bash → Python" 방향이다.
- #26(.mam.env 이중 로더)은 이 원칙의 작은 첫 사례다.
- #40(세션 ID 자동 확정)은 새 진입점의 resume/stop 흐름 위에 얹는다.
## 비범위
- 스킬의 동작 변경. 이 작업은 같은 동작을 문서에서 코드로 옮기는 것이다.
- bash 전면 재작성. 외부 프로세스 호출(herdr, 에이전트 CLI, git)은 bash 에 남아도 된다.
단계 1·2 가 PR #46(v4.8.3, 6af4a79)으로 병합됐습니다. 분류표는 이슈 댓글 대신 테스트 데이터 tests/data/skill_code_blocks.json 으로 들어갔습니다(45d1621 기준 37 블록: (a) 5 개 삭제, 다른 호출에 합쳐진 (c) 1 개 superseded, 현재 33 개). 가드 테스트 tests/test_issue42_skill_blocks.py 가 블록이 목록 없이 바뀌거나 지운 본문이 돌아오면 실패하므로, 단계 5 의 문서 가드는 일부 앞당겨진 셈입니다.
남은 단계: 3(현재 (b) 로 분류된 5 블록 = 스크립트에 없는 절차의 코드화), 4(bash 진입점 정리), 5(가드 확장). 단계 3·4 는 #17 항목 4(bash 판정의 Python 이전, 목록은 #17 댓글)와 같은 코드를 옮기므로 항목 4 다음에 진행합니다. 리뷰 경과와 후속은 PR #46 코멘트에 있습니다.
단계 1·2 가 PR #46(v4.8.3, 6af4a79)으로 병합됐습니다. 분류표는 이슈 댓글 대신 테스트 데이터 `tests/data/skill_code_blocks.json` 으로 들어갔습니다(45d1621 기준 37 블록: (a) 5 개 삭제, 다른 호출에 합쳐진 (c) 1 개 `superseded`, 현재 33 개). 가드 테스트 `tests/test_issue42_skill_blocks.py` 가 블록이 목록 없이 바뀌거나 지운 본문이 돌아오면 실패하므로, 단계 5 의 문서 가드는 일부 앞당겨진 셈입니다.
남은 단계: 3(현재 (b) 로 분류된 5 블록 = 스크립트에 없는 절차의 코드화), 4(bash 진입점 정리), 5(가드 확장). 단계 3·4 는 #17 항목 4(bash 판정의 Python 이전, 목록은 #17 댓글)와 같은 코드를 옮기므로 항목 4 다음에 진행합니다. 리뷰 경과와 후속은 PR #46 코멘트에 있습니다.
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
배경
스킬 여덟 개의 절차가 SKILL.md(합계 약 1,560줄)에 적혀 있고, 에이전트는 그 안의 코드 블록 32개(bash 22개)를 읽고 직접 따라 한다. 같은 일을 하는 스크립트가 이미 있는데도 문서가 절차를 따로 들고 있는 경우가 있다.
resume_session.sh가 전체 흐름(ID 해석, fresh-spawn 폴백, 기동, 시작 다이얼로그, YAML 갱신)을 하는데, SKILL.md 의 Workflow 는 같은 흐름을 36줄 bash 로 다시 적어 에이전트가 손으로 실행하게 한다. 둘 중 하나가 바뀌면 다른 쪽은 조용히 어긋난다.python3 -c/ bash 조각으로 문서에 있다.문서가 절차를 들고 있으면 (1) 에이전트마다 해석이 달라 같은 스킬이 다르게 실행되고, (2) 테스트가 문서 속 절차를 검증하지 못하며, (3) 모델이 바뀌거나 문맥이 요약될 때 단계가 빠진다. PR #41 리뷰에서 반복된 "bash 에 들어간 판정" 문제(#17 합의 D)와 #26 의 이중 로더도 같은 뿌리다.
원칙
python -m lib_py.<skill> <subcommand>형태의 명령 하나가 전체 흐름을 수행하고, 결과를 종료 코드와 한 줄 요약(필요하면--json)으로 돌려준다.--purge-conversation확인), 함정. 절차를 재현하는 코드 블록은 두지 않는다.범위(단계)
완료 조건
.claude/skills심볼릭 링크와 에이전트별 스킬 로딩 경로가 그대로 동작한다.관계
비범위
단계 1·2 가 PR #46(v4.8.3,
6af4a79)으로 병합됐습니다. 분류표는 이슈 댓글 대신 테스트 데이터tests/data/skill_code_blocks.json으로 들어갔습니다(45d1621기준 37 블록: (a) 5 개 삭제, 다른 호출에 합쳐진 (c) 1 개superseded, 현재 33 개). 가드 테스트tests/test_issue42_skill_blocks.py가 블록이 목록 없이 바뀌거나 지운 본문이 돌아오면 실패하므로, 단계 5 의 문서 가드는 일부 앞당겨진 셈입니다.남은 단계: 3(현재 (b) 로 분류된 5 블록 = 스크립트에 없는 절차의 코드화), 4(bash 진입점 정리), 5(가드 확장). 단계 3·4 는 #17 항목 4(bash 판정의 Python 이전, 목록은 #17 댓글)와 같은 코드를 옮기므로 항목 4 다음에 진행합니다. 리뷰 경과와 후속은 PR #46 코멘트에 있습니다.