연구 프로젝트 스캐폴드

논문 한 편이나 연구 하나를 저장소 하나로 관리하는 폴더 구조를 만든다. 원고, 기록, 코드, 자료, 결과를 한 저장소에 두고, 공개할 산출물이 있으면 공개 저장소를 따로 둔다. 만든 뒤의 세션 절차와 공통 규칙은 research-session을 따른다.

1. 틀의 정본

틀은 운영 체계 저장소(이 스킬이 들어 있던 저장소)의 scaffold/(new-project.sh와 template/)다. 사용자 컴퓨터에 그 저장소의 클론이 있으면 거기서 쓴다. 없으면 사용자에게 저장소 주소를 받아 클론한다. 명령은 그 저장소 루트에서 scaffold/new-project.sh로 부른다. 이 스킬에는 틀을 복사해 두지 않는다. 사본은 정본과 어긋나기 때문이다.

2. 값 정하기

대화에서 정해지지 않은 값만 묻는다. 기본값을 쓰면 그렇게 했다고 말한다.

3. 만들기

1. scaffold/new-project.sh <폴더> <이름> "<설명>" "<산출물 단위>" "<금지 행위>". 이미 있는 폴더면 끝에 --existing을 붙인다. 기존 파일은 덮지 않고, 겹치는 파일(AGENTS.md, CLAUDE.md, README.md, .gitignore)은 .scaffold를 붙여 둔다.
2. 에이전트가 돌릴 때는 SCAFFOLD_PUSH=n, 사용자 이름은 SCAFFOLD_USER="<이름>", 사용자 메일은 SCAFFOLD_EMAIL="<메일>", 도구는 SCAFFOLD_TOOLS="<도구>[,<도구>]"로 준다. 원격 저장소 생성과 push는 사용자 확인 뒤에 한다.
3. 프로젝트 설정(docs/설정.md)을 채운다. 도구 목록, 역할별 모델, 원고(언어, 투고처, 쪽 상한, 마감, 익명), 지킬 것(금지 행위, 자료 원칙). 여러 편을 함께 다루면 포트폴리오 폴더 경로와 공용 문헌 대장 경로도 적는다.
4. 커밋은 사용자와 도구가 함께 만든다. 스크립트는 새 저장소의 user.name과 user.email을 사용자 값으로 두고 core.hooksPath를 code/hooks로 건다. 작성자는 언제나 사용자이고, 도구가 만든 커밋은 접두와 함께 docs/설정.md 커밋 작성자 절의 공동 작성자 줄(Co-Authored-By:)을 메시지 끝에 붙인다. code/hooks/commit-msg가 작성자가 도구이거나 메일이 설정과 다를 때, 접두가 붙은 커밋에 공동 작성자 줄이 없을 때 커밋을 막는다. Claude 말고 다른 도구의 주소는 스크립트가 모르므로 설정의 표에 이름만 들어간다. 주소가 있으면 사용자와 채운다.
5. 도구가 하나면 인계 노트 폴더와 양식을 넣지 않고 세션 기록만 쓰는 틀이 만들어진다. 도구 이름은 커밋 접두, 세션 기록 파일 이름, 설정의 도구 표에 들어간다.
6. 공개 저장소를 둘 경우: 비공개 저장소 안에 공개 저장소를 하위 폴더로 두고 비공개 저장소의 .gitignore에서 뺀다. 공개 저장소에는 금지어 검사(운영 체계 저장소의 code/scripts/check-banned.sh)를 push 전 훅으로 건다. 거는 법은 그 스크립트 머리에 있다. 금지어 목록은 비공개 저장소에만 둔다.

4. 뒤처리

1. .scaffold 파일을 기존 파일과 손으로 합치고 지운다. 기존 내용을 버리지 않는다.
2. 만든 뒤에 도구를 더하거나 바꾸면 docs/설정.md의 도구 표와 커밋 작성자 절, code/hooks/commit-msg의 도구 목록, AGENTS.md, 00-교류/의 인계 노트 폴더(<보낸 도구>-to-<받는 도구>/)를 함께 고친다. 하나에서 둘로 늘리면 운영 체계 저장소의 scaffold/template/00-교류/에서 인계노트-양식과 폴더를 가져온다.
3. 현황의 산출물 표, 승인기록, 할일목록, 연구계획을 대화에서 정한 내용으로 채운다. 사용자 결정과 도구 권고를 구별한다.
4. --existing이면 첫 세션 기록과 첫 인계 노트를 실제로 한 일에 맞게 고친다.
5. 스크립트가 넣은 파일에 {{가 남았는지 본다. 기존 파일의 자리표시자는 일부러 둔 것일 수 있으니 건드리지 않는다.
6. 연결 폴더에서 git 커밋이 잠금 파일에서 멈추면 research-session 7절을 따른다.
7. 사용자에게 남은 명령(첫 커밋, 원격 저장소 생성)을 보이고, 만든 폴더의 README.md를 답에서 바로 열 수 있게 보인다.

5. 이미 있는 폴더를 옮길 때

몇 달 쓴 폴더에는 틀이 모르는 것이 있다. 클라우드 세션이 회차마다 남긴 git bundle, 그 안에만 있는 가지, 폴더 안에 들어 있는 다른 git 저장소, 1GB가 넘는 결과 파일. --existing을 돌리기 전에 아래 순서로 정리하고, 바꿀 것을 사용자에게 한 번에 물어 결정을 받는다(저장소 구성, 큰 파일, 폴더 재배치, 도구). 결정은 승인기록에 남긴다.

1. 살펴본다. 크기(du -sh */), 5MB 넘는 파일, 확장자 분포, 폴더 안의 .git(find . -name .git), bundle과 압축본, .env와 키 파일, 파일 이름의 유니코드 정규화(맥에서 만든 한글 이름은 NFD일 수 있다. NFC로 바꾼다. 섞이면 리눅스 클론에서 링크가 깨진다).
2. 폴더 안의 git 저장소. 원고나 코드가 따로 git 저장소면 그대로 submodule로 둔다(git submodule add <원격 주소> <경로>는 이미 있는 저장소도 등록한다). 흡수하면 가지 이력을 잃는다. 원격 주소는 아직 없는 저장소라도 정해서 적어 둔다. bundle이 있으면 먼저 code/scripts/restore-bundles.sh <저장소> <bundle 폴더>로 모든 가지를 그 저장소에 모은다. 같은 이름의 가지는 뒤 bundle이 이기고 갈라진 것은 <가지>@<bundle>로 남는다. 미커밋 수정은 가지 하나(<판>-wip)로 보존한다. main을 어느 가지에 둘지는 대리 판정으로 적는다. 원고는 최신 판으로 올리는 편이 맞고, 코드는 병행 가지가 있으면 기준선에 둔 채 현황에 최신 가지를 적는다.
3. 큰 파일을 셋으로 나눈다. 중복(bundle, 봉인 폴더의 tgz 압축본), 원자료(결과 tar.gz, 수십 MB jsonl), 산출물(바이트가 바뀌면 안 되는 공개 묶음, 검산 대상 표). 중복과 원자료는 _local/과 .gitignore로 빼고, 산출물은 ! 예외로 넣는다. 뺀 것은 현황의 잔여물 절에 적는다. 100MB 넘는 파일은 GitHub가 받지 않는다.
4. 폴더를 틀에 맞춘다. 옛 폴더와 새 폴더의 대조표를 먼저 쓰고(docs/00_현황 → docs/기록, docs/04_원고 → manuscript, code/rerun_* → results/seals/rerun_* 같은 식) mv한 뒤 md 파일의 경로 문자열을 긴 것부터 치환한다. 치환은 submodule 안은 건드리지 않는다. 끝나면 [..](..) 링크를 풀어 없는 파일을 세고, 옛 경로 대조표를 새 README에 넣는다. 옛 문서가 옛 경로를 적고 있어도 대조표가 있으면 읽힌다. 옛 README는 docs/기록/README_구판_<날짜>.md로 내린다.
5. 그 뒤에 --existing(3절)을 돌리고 4절대로 뒤처리한다. 현황의 산출물 표에는 submodule의 가지와 커밋을 적는다. 스킬을 프로젝트에 설치하면(install-skills.sh claude <폴더>) 설치 기록의 source가 설치한 환경의 경로로 적히므로, 연결 폴더 셸이나 클라우드에서 설치했으면 사용자 컴퓨터의 클론 경로로 고친다.
6. 자동 저장. 틀에 code/scripts/autosync.sh와 launchd/autosync.plist가 들어간다. 사용자 컴퓨터에서 30분마다 커밋·rebase·push하고 충돌이면 되돌리고 알린다. 설치는 사용자가 한다: gh auth setup-git, plist를 ~/Library/LaunchAgents/에 복사, launchctl load. 클라우드 세션은 research-session 3절대로 세션 끝에 push한다.
7. 원격 저장소. 저장소가 둘 이상이면(본 저장소, submodule) 사용자에게 만들 저장소 이름을 모두 보이고 gh repo create 명령을 한 줄씩 준다. submodule은 push --all과 --tags로 가지 전부를 올린다.

6. 하지 않을 것

• 기존 파일에 자리표시자 치환을 하지 않는다.
• 처음 만들 때 원격 저장소 생성과 첫 push는 사용자 확인 뒤에 한다. 그 뒤의 push는 research-session 3절을 따른다.
• 틀을 이 스킬 안에 복사해 두지 않는다.
• 폴더 안의 git 저장소를 지우거나 흡수하지 않는다. bundle은 복원이 끝나기 전에 지우지 않는다.