# 1.0 변경사항과 이전 버전 사용

AAPB 1.0은 오래 남길 프로젝트 기록, 필요한 산출물 형식, 선택한 전문 지침에 집중합니다. 패키지 이름은 `ai-agent-playbook`을 유지합니다. 설치 후 기본 명령도 `ai-agent-playbook`이며 `aapb`는 축약 명령입니다.

## 왜 개편했나요?

코딩 모델과 에이전트 앱의 기능이 좋아지면서 AAPB의 역할도 달라질 필요가 있었습니다. 앱이 이미 제공하는 계획·탐색·검토·실행을 일반 지침으로 반복하면 작업이 불필요하게 늘어날 수 있습니다. 이번 개편은 모델이 알아서 추론하기 어려운 프로젝트 결정, 검증 근거, 제품 제약, 요청한 형식, 분야별 예외에 집중하려는 선택입니다.

새 모델은 지침도 더 충실하게 따릅니다. 모호하거나 충돌하는 절차가 배경 설명으로 무시되지 않고 실제 동작에 영향을 줄 수 있습니다. [Astra 공식 안내](https://developers.openai.com/api/docs/guides/latest-model?model=gpt-6-astra)도 스킬을 감사하고 지침 우선순위를 명확히 하도록 권고합니다. 이는 지침을 검토할 이유이며 모두에게 맞는 스킬 개수를 정해 주는 기준은 아닙니다.

유용한 스킬의 가치는 남아 있습니다. [SkillsBench](https://arxiv.org/abs/2602.12670)는 시험한 구성에서 과제에 맞게 준비한 스킬의 이득을 확인했습니다. 그 결과가 모든 사용자의 전역 목록 크기나 AAPB의 성능 향상을 결정하지는 않습니다. 이번 개편의 목적은 역할을 명확히 하고 중복된 필수 작업을 줄이는 것이며, 측정하지 않은 속도·비용 이득을 보장하는 것은 아닙니다.

## 유지·변경·종료한 것

| 영역 | 1.0의 동작 |
| --- | --- |
| 프로젝트 작업 이어가기 | CURRENT.md에서 시작하고 필요한 상세 문서 연결. 기존 기록도 읽기 지원 |
| 전문 지침 | Core, development, 선택형 legacy 스킬과 해당 참고 자료 |
| 사람용 문서 | 초보자 안내, 상세 명령, 예시, 언어별 표현 유지 |
| 설치 | 기본 스킬 위치 하나, 명시적 선택, 소유권 확인, 복구 가능한 이전 |
| MCP | 프로젝트에 연결하는 선택형 읽기 전용 기록 도구 네 개 |
| 문서·UI 점검 | 도움이 될 때 선택하는 참고용 명령 |
| GitHub/Gitea | 검토한 협업 계획의 명시적 적용과 충돌 보고 |
| 실행·예약·광범위 분석 | 앱·프로젝트 도구 사용 또는 이전 런타임을 명시적으로 유지 |

이전 카탈로그는 진입점 94개였고, 1.0은 설치 가능한 스킬 여섯 개 중 개발 프로필에서 다섯 개를 선택합니다. 고유한 분야별 참고 자료는 보존했습니다. 이 수는 패키지 구성의 결과이며 여섯 개가 최적이거나 많은 스킬이 해롭다는 증거는 아닙니다. [스킬 카탈로그](skill-catalog.ko.md)와 [참고 자료 대응표](skill-decisions.ko.md)를 참고하세요.

## 필요한 지침의 양 선택하기

얼마나 많은 지침을 제공할지와 어떤 런타임 기능을 쓸지는 별개의 선택입니다.

| 필요한 것 | 현재 선택 방법 |
| --- | --- |
| 기록·산출물의 작은 기본 구성 | `--profile core` |
| 기록과 디자인·UI·문서 지침 | `--profile development` |
| 특정 레거시 계약 | `--profile legacy` 또는 개별 `--skill` |
| 한 작업에 필요한 추가 분야 지식 | 자료 전체를 읽지 않고 해당 참고 자료만 선택 |
| 이전의 넓은 스킬 목록과 실행기·예약기 | 0.5.11 패키지를 버전 고정해서 사용 |

앞으로 고유한 가치가 확인된 스킬을 더한 확장 프로필은 같은 1.0 런타임에서도 만들 수 있습니다. 반면 이전 런타임까지 “헤비” 스위치 하나로 되살리면 그 계약·의존성·유지보수 부담도 함께 돌아옵니다. 현재 라이트·헤비 런타임 전환은 구현하지 않았으며, 지금 프로필이 모두에게 최적임을 비교로 증명한 것도 아닙니다.

## 0.5.11을 계속 사용하려면

이전 스킬이나 런타임 기능에 의존한다면 바로 이전하지 않고 정확한 이전 버전을 사용할 수 있습니다.

```sh
npx ai-agent-playbook@0.5.11 --help
npx ai-agent-playbook@0.5.11 skills install --dry-run
```

전역에서 유지하려면 다음을 사용합니다.

```sh
npm install -g ai-agent-playbook@0.5.11
aapb --version
```

0.5.11의 전역 명령은 `aapb`이며 새 전체 이름의 실행 명령은 없습니다. 0.5.11 사용법에서 1.0의 `ai-agent-playbook` 명령으로 바꿔 실행하지 마세요. 전역 버전을 바꾸면 기존 호출도 영향을 받습니다. 두 버전이 필요하면 버전 고정 `npx`나 별도 설치 폴더를 사용합니다.

구버전 스킬도 적용 전에 미리 봅니다. 큰 카탈로그를 복원하려고 1.0 설치본이나 사용자 수정을 덮어쓰지 마세요. 이전 패키지, 스킬, 기록, 복구 자료를 보관합니다. 기존 예약과 원격 기록은 자동으로 변경하지 않습니다. 설치와 보호된 복구는 [설치 안내](lifecycle.ko.md)에 있습니다.

## 새 방식이 맞을 때 이전하기

기존 기록을 먼저 읽고 선택한 스킬 이전을 미리 봅니다. 구버전 기록을 읽기 위해 레이아웃까지 바꿀 필요는 없습니다. 루트 지침, 과거 결정, 사용자 편집을 보존하세요. 실제 운영에 쓰는 런타임을 바꾸기 전에 대표 프로젝트에서 시험합니다.

코드 테스트, 패키지 설치, MCP 통신, 앱의 스킬 발견, 실제 작업 결과는 구분해서 검증합니다. 최초 소규모 품질 비교가 가벼운 구성이 모든 작업을 개선한다고 증명하지는 못했습니다. 모델과 프로젝트 요구는 바뀔 수 있으므로 예전 필수 절차 전체를 되살리지 않고도 유용한 지침을 추가할 여지를 남깁니다.