jksim/agent-skills-jksim

레이아웃 마이그레이션

개요

업스트림 agent-skills는 작업 파일을 프로젝트 루트에 유지합니다. 팀은 이 파일들을 .claude-work/에 보관합니다 (팀 오버라이드의 Paths 표 참조). 이 스킬은 진행 중인 프로젝트를 한 번의 커밋으로 팀 레이아웃으로 이동합니다. 각 파일은 Git 히스토리를 유지합니다. 작업 체크박스도 파일과 함께 이동하므로 중단된 지점부터 계속 작업할 수 있습니다.

인수는 플랜 및 작업 파일의 <id>입니다. 예: /agent-skills-jksim:migrate-layout fl-debug.

사용 시기

• 프로젝트 루트에 SPEC.md, tasks/plan.md, tasks/todo.md 또는 CONSTRAINTS.md가 있는 경우.
• 프로젝트에 루트 작업 파일과 .claude-work/가 모두 있는 경우.

새 프로젝트에는 사용하지 마십시오. 명세 단계에서는 처음부터 .claude-work/에 기록합니다.

프로세스

1. 시작 상태 확인

다음 중 하나가 참이면 멈추고 사용자에게 알립니다:

• 폴더가 Git 저장소가 아닌 경우.
• git status --porcelain --untracked-files=no에서 추적된 파일에 변경 사항이 표시되는 경우. 사용자에게 먼저 커밋하거나 스태시(stash)하도록 요청합니다. 추적되지 않은 파일은 그대로 둘 수 있습니다: 8단계에서 git add -u를 사용하여 스테이징하므로 추가되지 않습니다.
• git check-ignore -q .claude-work/spec/SPEC.md가 성공하는 경우. 파일 경로를 확인합니다: .claude-work/와 같은 패턴은 폴더가 존재하기 전에는 일치하지 않습니다. 소비자 프로젝트는 .claude-work/를 커밋합니다.

2. 이전 파일 찾기

프로젝트 루트 기준으로 다음 경로만 확인합니다:

이전 경로	팀 경로
SPEC.md, docs/SPEC.md	.claude-work/spec/SPEC.md
SPEC-<module>.md	.claude-work/spec/SPEC-<module>.md
CAPABILITY-MAP.md	.claude-work/spec/CAPABILITY-MAP.md
tasks/plan.md	.claude-work/tasks/plan-<id>.md
tasks/todo.md	.claude-work/tasks/todo-<id>.md
CONSTRAINTS.md	.claude-work/docs/CONSTRAINTS.md
docs/ideas/<name>.md	.claude-work/docs/ideas/<name>.md
docs/intent/<topic>.md	.claude-work/docs/intent/<topic>.md
docs/decisions/	유지. 물어보기 (4단계 참조)

spec/은 건드리지 마십시오. RSpec 및 기타 테스트 레이아웃에서 사용합니다.

Git이 추적하는 파일만 사용합니다 (git ls-files). git mv는 다른 파일에서 실패합니다. 추적되지 않거나 무시된 이전 파일이 있으면 이름을 알려주고 사용자에게 물어보십시오.

이전 파일이 없으면 마이그레이션할 항목이 없다고 사용자에게 알립니다. 중단합니다.

3. <id> 가져오기

인수를 사용합니다. 인수가 없으면 프로젝트 이름에서 짧은 케밥-케이스(kebab-case) id를 제안하고 사용자에게 물어보십시오. tasks/plan.md 또는 tasks/todo.md가 없으면 이 단계를 건너뜁니다.

4. 계획 표시 및 승인 대기

이전 경로, 새 경로를 보여주는 하나의 표를 표시합니다. 그런 다음 각 충돌을 나열하고 물어보십시오:

• 대상 존재: 이미 팀 경로에 파일이 있는 경우. 해당 파일을 이동하지 마십시오. 어떻게 할지 물어보십시오.
• 두 개의 명세: SPEC.md와 docs/SPEC.md가 모두 존재하는 경우. 어느 것이 명세인지 물어보십시오.
• tasks/의 다른 파일: plan.md와 todo.md만 이동합니다. 다른 파일들의 이름을 알려주십시오.
• docs/decisions/가 존재: 기본값은 유지입니다. 프로젝트가 자체 ADR 폴더를 유지하기 때문입니다. 사용자가 요청할 때만 .claude-work/docs/adr/로 이동합니다.

사용자가 표를 승인할 때까지 아무것도 이동하지 마십시오.

5. git mv로 이동

각 파일에 대해 git mv <old> <new>를 실행합니다. 대상 폴더를 먼저 만듭니다 (mkdir -p). 복사 후 삭제하지 마십시오: git mv는 히스토리를 유지합니다. tasks/가 비어 있으면 rmdir tasks를 실행합니다.

6. 실시간 참조 수정

프로젝트에서 이전 경로를 검색합니다: git grep -n -E 'SPEC(-[A-Za-z0-9_-]+)?\.md|CAPABILITY-MAP\.md|CONSTRAINTS\.md|tasks/(plan|todo)\.md|docs/(ideas|intent|decisions)/'.

또한 파일 이름 자체를 검색합니다. 이동된 파일이 폴더 없이 파트너를 지칭할 수 있기 때문입니다: git grep -n -E '(^|[^-/A-Za-z0-9_])(plan|todo)\.md'. 예: 플랜의 "todo.md의 세부 사항"은 "todo-.md의 세부 사항"이 됩니다.

실시간 참조는 독자나 에이전트에게 파일의 현재 위치를 알려줍니다. 변경합니다:

• CLAUDE.md: "SPEC.md: 승인된 명세"는 ".claude-work/spec/SPEC.md: 승인된 명세"가 됩니다.
• README.md: [SPEC.md](SPEC.md)는 [SPEC.md](.claude-work/spec/SPEC.md)가 됩니다.
• 이동된 파일 내의 상대 링크: 이전 tasks/plan.md의 ../SPEC.md는 .claude-work/tasks/plan-<id>.md의 ../spec/SPEC.md가 됩니다.
• CLAUDE.md의 제약 조건 포인터 라인.
• 각 이동된 파일 내의 다른 상대 링크. 이동된 파일은 새 깊이에 있으므로 이동하지 않은 파일에 대한 링크도 깨집니다. 예: 루트 SPEC-foo.md의 [x](src/a.kt)는 .claude-work/spec/SPEC-foo.md의 [x](../../src/a.kt)가 됩니다.

기록은 과거에 일어난 일을 알려줍니다. 그대로 둡니다:

• 완료된 작업 항목: "파일: README.md, SPEC.md".
• 변경 로그, 리뷰 노트 또는 커밋 메시지.

확실하지 않은 경우 텍스트를 그대로 두고 7단계에 나열합니다.

7. 결과 표시

git status, 변경된 참조의 diff, 그리고 변경하지 않은 이전 경로 참조 목록을 각각의 이유와 함께 표시합니다.

8. 한 번에 커밋

git mv가 이미 이동을 스테이징했습니다. 편집된 참조를 git add -u로 스테이징합니다. git add -A를 사용하지 마십시오: 관련 없는 파일을 추가할 수 있습니다. Move working files to .claude-work 메시지로 커밋합니다. 푸시(push)하지 마십시오.

훅(hook)이 커밋을 거부하면 중단하고 보고합니다. --no-verify를 사용하지 마십시오.

9. 다음 단계 보고

이동된 파일과 유지된 파일을 사용자에게 알립니다. .claude-work/docs/VOCABULARY.md가 없으면 다음 명세 단계에서 생성한다고 말합니다 (규칙 2). 지금 생성하지 마십시오.

일반적인 합리화

합리화	현실
"복사가 git mv보다 간단합니다."	복사는 파일 히스토리를 잃습니다. 리뷰어와 git log --follow가 필요합니다.
"SPEC.md의 모든 언급을 업데이트하겠습니다."	기록은 과거를 설명합니다. 변경하는 것은 역사를 다시 쓰는 것입니다.
"트리가 조금만 더러워졌습니다."	커밋되지 않은 작업이 마이그레이션 커밋에 포함됩니다. 먼저 사용자에게 물어보십시오.
"계획이 명확하므로 승인을 건너뛰겠습니다."	사용자가 <id>와 각 충돌을 결정합니다. 기다리십시오.

위험 신호

• git log --follow에 마이그레이션 커밋 이전의 히스토리가 표시되지 않음.
• 완료된 작업 항목 또는 변경 로그가 당시 존재하지 않았던 팀 경로를 지칭함.
• 사용자 승인 없이 spec/ 또는 docs/decisions/가 이동됨.
• 하나를 초과하는 커밋 또는 푸시(push).

검증

• 각 이전 파일이 팀 경로에 있습니다. 사용자가 유지하기로 선택한 파일을 제외하고 루트에 이전 파일이 남아 있지 않습니다.
• git log --follow <new path>가 이전 히스토리를 보여줍니다.
• 실시간 참조가 팀 경로를 가리킵니다. 기록은 변경되지 않았습니다.
• 작업 체크박스가 변경되지 않았습니다.
• 하나의 커밋, Move working files to .claude-work. git status가 깨끗합니다. 푸시(push)되지 않았습니다.