# 기존 저장소에 적용하기

먼저 저장소의 기존 지침과 기록을 확인합니다. AAPB는 과거 기록을 다시 만들지 않고 읽을 수 있습니다. Bootstrap은 기존 내용을 보존하며 없는 기록을 만들거나 명시적으로 선택한 안내·링크·제외 규칙을 추가할 수 있습니다.

## 쓰기 전에 확인하기

```sh
ai-agent-playbook records status "<project>" --json
ai-agent-playbook records status "<project>" --view records --json
ai-agent-playbook bootstrap "<project>" --local-only --dry-run
```

`--local-only`는 Git의 `info/exclude`를 사용하는 `--exclude local`의 호환 별칭입니다. AAPB는 설정 루트를 포함하는 Git 저장소를 찾으므로 선택한 폴더에 별도의 `.git` 디렉터리가 없어도 됩니다. 하위 프로젝트 폴더와 연결된 worktree도 지원하며 worktree끼리 제외 파일을 공유할 수 있습니다. Git 밖에서 인자로 로컬 제외를 요청해도 기록 생성은 허용하고 제외를 건너뛰었다고 표시하며 Git을 초기화하지 않습니다. `AGENTS.md`와 상태 조회에 나온 시작 문서를 읽으세요. 어떤 문서를 바꿀지 정하기 전에 Git이 있다면 커밋하지 않은 변경도 확인합니다.

| 기존 상태 | 다음 단계 |
| --- | --- |
| 플레이북 없음 | 생성 미리보기를 검토한 뒤 기록 생성 |
| CURRENT.md와 상세 기록이 있음 | 기존 문서를 읽고 현재 작업과 관련된 사실만 갱신 |
| 구버전의 구조화 기록이 있음 | 그대로 읽기. 이전은 선택 사항 |
| 인식 가능한 플레이북 폴더가 여러 개 | 기준 기록이 무엇인지 먼저 명시적으로 정리 |
| 관리 정보가 수정되었거나 소유권이 불명확함 | 보존. 읽기는 가능해도 이전은 거부될 수 있음 |

## 새 기록 생성하기

```sh
ai-agent-playbook bootstrap "<project>" --local-only
```

이 인자형 실행은 최소 기록을 사용하고 로컬 제외를 요청합니다. `--records standard`로 작업 일지·지식 안내를, `--lang en|ko`로 새 문서 언어를 선택할 수 있습니다. `--agents link`는 기존 지침을 교체하지 않고 짧은 기록 링크를 추가합니다. 기본값은 `--agents preserve`이며 `--preserve-agents`도 호환 별칭으로 유지합니다. 과거의 루트 지침 교체 방식은 계속 지원하지 않습니다.

[라이트 스킬 프로필](skill-catalog.ko.md#라이트-모드)은 별도의 설치 선택입니다. 부트스트랩은 스킬을 불러오거나 전역 응답 문체를 설정하지 않습니다. 처음 만드는 기록 파일을 줄이려면 기존 `--records minimal` 선택을 사용하세요. 라이트는 표준 구성이나 기존 기록에도 사용할 수 있습니다. Git 제외는 모델 입력이나 서비스 감사 기록을 제어하지 않습니다.

다시 실행하면 기존 문서, 메타데이터와 등록을 보존합니다. 없는 표준 안내와 명시적으로 선택한 AGENTS 링크를 추가할 수 있으며 제외 선택에 따라 수정되지 않은 AAPB 관리 규칙을 옮길 수 있습니다. 예정된 작업과 반환된 백업을 확인하세요. 사용자 규칙과 추적 중인 파일은 보존합니다. 제외 항목이 이미 커밋된 파일의 추적을 해제하지는 않습니다.

## 공유 여부와 관리 범위 정하기

커밋할 수 있게 둘 기록은 `--exclude none`을 선택합니다. 기존 사용자·전역 규칙 때문에 여전히 제외될 수 있으므로 실제 Git 상태도 확인하세요. AAPB는 파일을 스테이징하거나 커밋하지 않습니다. 개인 실행 결과와 절대 경로는 프로젝트에서 정한 로컬 전용 위치에 둡니다.

소유권 표식은 확인된 관리 파일만 대상으로 합니다. 사용자 문서와 루트 지침을 다시 생성해도 되는 템플릿 출력으로 취급하지 않습니다. 기록 구조 이전에는 수정되지 않은 관리 정보가 필요합니다. 충돌을 피하려고 해시나 소유권을 만들어 넣지 마세요.

## 제외 방식을 고르고 설정 다시 확인하기

| 방식 | 효과 |
| --- | --- |
| `local` | 대상 기록 경로를 Git의 `info/exclude`에 추가하며 연결된 worktree가 같은 파일을 쓸 수 있습니다. Git 밖에서는 안내의 항목을 비활성 상태로 표시하고 이유를 알려줍니다. 인자로 로컬 제외를 명시하면 제외를 건너뛰었다고 알리고 기록은 계속 사용합니다. |
| `shared` | `.gitignore`에 제외 규칙을 추가합니다. 직접 커밋하면 규칙을 공유하며 기록 자체는 제외됩니다. |
| `global` | 사용자 Git 제외 파일을 사용하므로 같은 파일을 쓰는 다른 저장소에도 영향을 줍니다. 범위를 명시적으로 검토하세요. |
| `none` | 규칙을 추가하지 않습니다. 관리 중인 방식을 전환할 때 이 대상의 수정되지 않은 AAPB 규칙만 제거합니다. |

```sh
ai-agent-playbook bootstrap "<project>" --records standard --exclude shared --agents preserve --dry-run --json
ai-agent-playbook bootstrap "<project>" --records standard --exclude shared --agents preserve --json
```

어느 방식도 스테이징, 추적 해제나 커밋을 하지 않습니다. 사용자 규칙과 공유 제외 규칙의 우선순위가 실제 Git 결과에 영향을 줄 수 있습니다. 기록이 하위 저장소 밖에 있다면 모든 구성원에 제외를 추가할 필요는 없습니다. 반환된 복구 기록을 보존하고 제외·AGENTS 링크 변경에는 [부트스트랩 복구](lifecycle.ko.md)를 사용합니다.

별도 선택 없이 대화형 bootstrap을 실행하면 안내를 제공하며 `--interactive`로 명시적으로 요청할 수도 있습니다. 새 설치에서는 프로젝트나 상위 폴더를 확인하는 준비 단계를 보여줍니다. 작업 공간의 하위 저장소는 직접 준비한 뒤 계속하세요. AAPB는 최종 적용 후 없는 기록 폴더를 만들며 저장소를 옮기거나 clone하지 않습니다. 기존 작업 공간의 등록은 유지하고 구성원 변경에는 `workspace add/remove`를 사용합니다.

권장 항목과 현재 설정은 따로 표시합니다. 표준 안내와 Git이 있을 때 로컬 제외·Git 밖일 때 제외 없음은 권장 사항이며 자동 선택하지 않습니다. 단일 항목은 번호나 방향키로 이동한 뒤 Enter로 선택합니다. Enter만 누르면 넘어가지 않습니다. 저장소 체크박스는 Space로 선택하고 Enter로 확정하세요. `q`와 키 도움말은 목록 위에 있으며, 검색 입력 밖에서는 가능한 경우 Esc나 `b`로 이전 단계로 돌아갑니다. 최종 검토의 설정 수정하기로 항목을 고친 뒤 다시 검토할 수 있습니다. 결과는 선택한 언어의 읽기 쉬운 문장과 다음 행동으로 표시합니다.

`--yes`는 질문 없이 기존 기본값과 저장된 설정을 사용하며 명시한 옵션을 우선합니다. 인자형·비대화형 실행은 별도로 지정하지 않으면 최소·제외 없음 기본값을 유지합니다. `--json`은 질문 없이 구조화 결과를 반환합니다. 검색·번호 범위·키 조작은 [명령어 가이드](commands.ko.md), 구성원 등록은 [작업 공간](workspaces.ko.md)을 참고하세요.

## 아키텍처와 루트 지침

부트스트랩은 소스 아키텍처를 선택하거나 이전하지 않습니다. 채택한 프로젝트 경계와 기존 AGENTS.md를 유지합니다. 지침이나 아키텍처 결정을 작성할 필요가 있을 때 [기술 중립 프로젝트 템플릿](../templates/agents/AGENTS.ko.md)과 [아키텍처 안내](project-architecture.ko.md)를 조정해 사용하세요. 의존성에 특정 기술이 있다는 이유로 예전 프로필을 적용하거나 소스를 옮기지 않습니다.

## 기존 기록은 필요한 부분부터 갱신하기

과거 결정과 근거 링크를 보존합니다. 확인한 현재 사실로 CURRENT.md를 추가하거나 갱신하고, 필요한 상세 문서만 연결하세요. 오래된 실행 보고서를 오늘의 상태로 자동 요약하지 않습니다. 애플리케이션은 자체 명령으로 시험하고 실제 확인 범위를 기록합니다.

의미 있는 진척의 일지와 현재 지식은 [오래 유지할 기록](durable-records.ko.md), 작성 예시는 [기록 구조](structured-playbook-layout.ko.md), 이전 미리보기·적용·복구는 [설치 안내](lifecycle.ko.md)에 있습니다. 원본을 보존하며 이전을 시험하려면 [로컬 시연](demo.ko.md)처럼 기록 복사본을 사용하세요.

## 0.5에서 올릴 때 기존 지침 검토하기

npm 업데이트, 스킬 설치, 기록 구조의 관리 정보 이전은 기존 프로젝트 지침을 다시 쓰지 않습니다. 과거 기록은 정상적으로 읽혀도 현재 지침에 종료된 명령이나 없는 스킬이 남아 있을 수 있습니다. 기록 검증은 구조와 소유권을 검사하며, 문서의 모든 지침이 최신인지 판단하지 않습니다.

1. 편집할 지침을 백업하고 Git 추적 여부와 로컬 전용 규칙을 확인합니다. 실제 시작 문서와 그 문서로 안내하는 프로젝트 규칙을 읽습니다.
2. 현재 사용하는 `AGENTS.md`, `CURRENT.md`와, 있다면 `START_HERE.md`, `policy/SKILLS.md`를 검토합니다. 이번 이전과 관련된 링크만 따라가세요. 과거 작업일지에서 검색된 내용은 당시의 근거이며, 일괄 수정할 파일 목록이 아닙니다.
3. 아래 대응표를 참고해 지원되지 않는 안내를 고칩니다. 제품 결정, 아키텍처 경계, 승인 요건과 프로젝트별 검증 명령은 보존합니다.
4. 직접 검토한 파일 편집으로 CURRENT.md를 현재 상태의 진입점으로 삼습니다. 유용한 탐색 문서와 상세 사용법은 유지하세요. 날짜별 이력 때문에 다음 행동을 찾기 어렵다면 원문을 연결된 별도 기록으로 옮기고, 이를 새로 검증한 사실로 요약하지 않습니다.
5. 이전 대화가 없는 새 세션에서 수정한 시작 문서와 인계를 읽습니다. 변경 범위, 보존할 결정, 다음 행동과 미검증 항목을 찾을 수 있는지 확인합니다.

| 현재 지침에 남은 0.5 안내 | 현재 방식 |
| --- | --- |
| `operator context` 또는 과거 카탈로그·색인 도구 | 기록은 `records read` / `records search` 또는 해당 MCP 도구로 조회. 소스 파일은 일반 프로젝트 도구로 읽기 |
| `run start` 또는 필수 AAPB 실행 루프 | 에이전트 앱의 일반 실행 도구를 사용하고 의미 있는 시점에 기록 작성 |
| 과거 MCP 리소스·워크플로 프롬프트·쓰기 활성화 옵션 | 실제 제공되는 네 도구를 확인하고, 기록은 파일 편집이나 지원되는 명시적 CLI로 갱신 |
| 폐기된 스킬 이름 또는 모든 스킬의 순차 실행 | [스킬 목록](skill-catalog.ko.md)에서 현재 기능을 선택하고 유용한 프로젝트 계약은 프로젝트 문서에 보존 |
| 진입할 때마다 모든 지도·계획·작업일지 읽기 | 현재 상태에서 시작하고 이번 작업에 필요한 참조만 읽기 |

과거 작업을 설명하는 명령과 근거는 그대로 둡니다. 오래된 지침을 충족하려고 폐기된 스킬을 재설치하거나, `managed-modified` 결과를 없애려고 소유권 해시를 바꾸거나, 프로젝트 지침 전체를 템플릿으로 교체하지 마세요. 의도적인 구버전 복구는 [설치 안내](lifecycle.ko.md)에서 설명합니다.

기록 검증과 애플리케이션 검증은 별개입니다. 읽기에 성공했다고 과거 구현 주장이 지금도 참임을 입증한 것은 아닙니다. 새 세션에서 호스트 도구 실패나 근거 누락을 보고했다면 인계에 그 한계를 남기고, 전체 흐름이 검증됐다고 표현하지 않습니다.