setup
이 스킬은 채택자 프로젝트가 커밋하는 유일한 프레임워크 아티팩트입니다. 다른 모든 아파치 매파이 스킬(security, pr-management, issue)은 이 스킬이 관리하는 gitignore된 스냅샷 <snapshot-dir>에 대한 심볼릭 링크입니다.
채택 모델은 스냅샷 + 에이전트 재정의 + 드리프트 인식 업데이트입니다(서브모듈, 마켓플레이스, 복사본 아님):
- 프레임워크는
<snapshot-dir>에 다운로드되어 채택자 저장소에서 gitignore됩니다. 스냅샷은 빌드 아티팩트이지 소스가 아닙니다. - 세 가지 설치 방법이 지원됩니다(그대로 복사하여 붙여넣기 가능한 레시피는
docs/setup/install-recipes.md참조):- svn-zip — ASF 배포판에서 제공하는 서명된 zip (릴리스가 배포되면 프로덕션에 권장).
- git-tag — 특정 git 태그에 고정.
- git-branch — 브랜치 팁을 추적(기본값:
main, WIP 경로).
- 두 개의 잠금 파일이 프레임워크 버전을 기록합니다. 커밋된 잠금 파일은 프로젝트가 고정한 버전을 선언하고, 로컬 잠금 파일은 각 시스템이 실제로 가져온 버전을 기록합니다. 둘 사이의 드리프트는
/magpie-setup upgrade를 통해 표시되고 해결됩니다. - 심볼릭 링크는 프레임워크 스킬이 채택자 저장소에 있는 것처럼 호출 가능하게 만듭니다. 각 심볼릭 링크는
magpie-<framework-skill>형식으로 명명됩니다. 모든 프레임워크 스킬은magpie-접두사 아래 설치되어 채택자 고유의 스킬과 충돌하지 않도록 네임스페이스가 지정됩니다(예: 스냅샷의skills/pr-management-triage/는magpie-pr-management-triage가 되며/magpie-pr-management-triage로 호출됨)..agents/skills/는 유일한 표준 위치입니다: 이 디렉토리의magpie-*항목은<snapshot-dir>/skills/<framework-skill>/을 가리킵니다. 다른 모든 에이전트 대상(.claude/skills/,.github/skills/, ...)은 스킬별 릴레이 심볼릭 링크를 받아 표준 항목을 다시 가리킵니다(.claude/skills/magpie-<n>→../../.agents/skills/magpie-<n>) — 채택 프로젝트가 이전에 어떤 레이아웃을 사용했든 상관없습니다(agents.md참조). 심볼릭 링크는 gitignore됩니다. 대상이/magpie-setup이 실행되기 전 새 클론에서 사라지기 때문입니다. - 프레임워크 워크플로우에 대한 채택자별 수정은
.apache-magpie-overrides/<skill-name>.md(커밋됨)에 에이전트가 읽을 수 있는 지침으로 저장됩니다. 이 지침은 프레임워크 스킬이 실행할 단계를 무효화하거나 변경합니다. 자세한 내용은overrides.md(계약)와docs/setup/agentic-overrides.md(설계 근거)를 참조하세요.
로컬 자체 채택(프레임워크 체크아웃 전용). 스냅샷 메커니즘으로 채택할 수 없는 유일한 저장소는 아파치 매파이 프레임워크 체크아웃 자체입니다 — 프레임워크의 원격 스냅샷을 자체로 가져오는 것은 순환적입니다. 대신 method:local로 자체 채택합니다: .agents/skills/의 각 표준 magpie-<skill>은 저장소 내 ../../skills/<skill>/ 소스를 가리키는 커밋된 심볼릭 링크이고, 다른 모든 활성 에이전트 대상(agents.md) — .claude/skills/(Claude Code), .github/skills/(GitHub의 스킬 로더), 기타 존재하는 대상 — 은 magpie-<skill> → ../../.agents/skills/magpie-<skill> 형식의 커밋된 릴레이 심볼릭 링크를 받습니다. 스냅샷, 원격 가져오기, 복사본이 없습니다. 이를 통해 프레임워크를 개발하는 동안 자체 스킬을 호출할 수 있으며, 모든 기여자는 설정 단계 없이 새 클론에서 활성 상태로 스킬을 사용할 수 있습니다. adopt는 프레임워크 체크아웃을 구조적으로 감지하여 자동으로 라우팅합니다(adopt.md → 로컬 자체 채택 참조).
두 개의 잠금 파일
프레임워크의 잠금 파일 모델은 프로젝트가 고정한 버전(커밋됨)과 이 시스템이 실제로 가져온 버전(로컬)을 분리합니다. 이 분할은 드리프트 감지와 다중 설치 프로그램 지원의 기초입니다.
<committed-lock> — .apache-magpie.lock
채택자 저장소 루트에 커밋됨. 프로젝트의 고정 버전.
/magpie-setup만 수정합니다. 수동으로 수정하지 마세요.
# .apache-magpie.lock — 커밋됨; 프로젝트의 고정 버전.
method: <git-branch | git-tag | svn-zip>
url: <방법별 형식은 아래 참조>
# method=git-branch의 경우:
ref: main
# method=git-tag의 경우:
ref: v1.0.0 # 태그 이름
commit: <SHA> # 커밋 시 태그가 가리키던 커밋
# method=svn-zip의 경우:
ref: 1.0.0 # 버전 번호
sha512: <hash> # 출시된 zip의 SHA-512 (재가져오기 검증용)
다음 /magpie-setup adopt를 실행하는 채택자는 이 파일을 읽고 프로젝트가 선언한 동일한 버전을 다시 설치합니다. 이것이 "한 번 채택하면 이후 모든 사용자가 동일한 것을 얻는다"는 약속의 핵심입니다.
<local-lock> — .apache-magpie.local.lock
채택자 저장소 루트에 gitignore됨. 로컬 스냅샷의 지문. 이 시스템이 가져온 내용과 시점을 기록합니다.
# .apache-magpie.local.lock — gitignore됨; 시스템별.
source_method: <git-branch | git-tag | svn-zip>
source_url: <스냅샷을 실제로 가져온 URL>
source_ref: <실제로 가져온 브랜치 / 태그 / 버전>
fetched_commit: <현재 디스크에 있는 커밋 SHA>
fetched_at: <ISO-8601 타임스탬프>
모든 프레임워크 스킬 호출 시 드리프트 검사는 이 파일을 <committed-lock>과 비교하여 불일치를 제안된 /magpie-setup upgrade로 표시합니다.
이 디렉토리의 세부 파일
| 파일 | 목적 |
|---|---|
adopt.md | 첫 번째 채택 안내 — 기존 스냅샷 인식 vs 부트스트랩 필요, 두 잠금 파일 작성, 사용자에게 연결할 스킬 패밀리 질문, gitignore된 심볼릭 링크 생성, .apache-magpie-overrides/ 스캐폴드, 포스트-체크아웃 훅 설치, 프로젝트 문서 업데이트. 기본 하위 액션. |
upgrade.md | 커밋된 잠금에 따라 gitignore된 스냅샷 새로고침, 새로운 프레임워크 구조에 맞게 에이전트 재정의 + 심볼릭 링크 조정, 충돌 표시. 드리프트 해결 흐름을 구동합니다. |
verify.md | 읽기 전용 상태 확인 — 스냅샷 존재 + 온전함, 두 잠금 파일 동기화, 심볼릭 링크가 라이브 대상 가리킴, .gitignore 정확함, .apache-magpie-overrides/ 존재, 드리프트 상태(커밋 vs 로컬), setup 스킬 자체가 최신인지 확인. |
agents.md | 에이전트 대상 레지스트리 — 벤더 전반에서 프레임워크 스킬 심볼릭 링크가 배치되는 디렉토리, 그리고 표준-더하기-릴레이 모델: .agents/skills/는 유일한 표준 위치(스냅샷/소스를 가리킴); 다른 모든 대상(claude-code, github, 네이티브 홀드아웃(Windsurf/Goose 등))은 스킬별 릴레이 심볼릭 링크를 .agents/skills/로 받음. 활성 대상 선택, SKILL.md 형식 이식성, Claude Code 전용 레이어(sandbox/hooks)를 정의합니다. 모든 하위 액션이 대상 집합을 위해 참조하는 진리 소스입니다. |
overrides.md | 에이전트 재정의 파일 관리 — 프레임워크 스킬에 대한 재정의 열기/스캐폴드, 기존 재정의 나열, 업그레이드 시 프레임워크가 기본 스킬 구조를 변경할 때 조정 지원. |
unadopt.md | 채택 해제 — 스냅샷, 잠금, 심볼릭 링크, 포스트-체크아웃 훅, .gitignore 항목, README.md / AGENTS.md / CONTRIBUTING.md의 채택 섹션, 커밋된 setup 스킬 자체 제거. 기본적으로 .apache-magpie-overrides/를 보존합니다. --purge-overrides는 함께 제거합니다. 모든 쓰기 전에 전체 제거 계획을 표시합니다. |
황금 규칙
황금 규칙 1 — 스냅샷을 절대 수정하지 마세요. <snapshot-dir>은 빌드 아티팩트이며, gitignore되고 채택자 관점에서 읽기 전용입니다. 채택자가 원하는 모든 수정은 .apache-magpie-overrides/에 넣어야 합니다(여기서 커밋되며 다음 upgrade에도 유지됨). 이 스킬 및 다른 프레임워크 스킬이 런타임에 재정의를 참조할 때, 절대 <snapshot-dir>에 쓰지 않습니다.
황금 규칙 2 — <committed-lock>은 프로젝트의 고정 버전이고; <local-lock>은 시스템별 진실입니다. 서로 다른 목적을 제공하며 다른 위치에 있습니다:
<committed-lock>은 프로젝트가 사용하는 버전을 선언합니다./magpie-setup adopt를 먼저 실행한 채택자(또는 나중에/magpie-setup upgrade를 실행하고 새 고정을 수락한 사람)가 수정합니다. 버전 올리기는 의도적인 프로젝트 수준의 작업이며, 그 변경은 이를 제안한 PR의git diff에 나타납니다.<local-lock>은 이 시스템이 설치한 버전을 기록합니다./magpie-setup adopt와/magpie-setup upgrade에 의해 자동으로 업데이트됩니다. 개발자별, 체크아웃별, 워크트리별입니다.
황금 규칙 3 — 드리프트가 발생하면 드리프트를 해결합니다. 모든 프레임워크 스킬(및 /magpie-setup verify)은 실행 시작 시 <committed-lock>과 <local-lock>을 비교합니다. 불일치 시 스킬은 차이를 표시하고 /magpie-setup upgrade를 제안합니다. 사용자는 수락하거나 연기합니다. 수락하면 upgrade는:
<snapshot-dir>을 완전히 삭제합니다.- 커밋된 잠금(프로젝트가 선택한 새 버전)에 따라 다시 설치합니다.
- gitignore된 프레임워크 스킬 심볼릭 링크를 새로고침합니다 — 사용자의 패밀리 선택이 포함하는 새 프레임워크 스킬을 추가하고, 이름이 변경되거나 제거된 프레임워크 스킬을 제거합니다.
- 새 프레임워크 구조에 대해 에이전트 재정의를 조정합니다(충돌 표시; 자동 재작성하지 않음).
<local-lock>을 새 가져오기로 업데이트합니다.
황금 규칙 4 — .gitignore는 채택자 저장소를 깨끗하게 유지합니다. 채택자 저장소에서 gitignore되는 세 가지:
<snapshot-dir>(전체 프레임워크 스냅샷 — 잠재적으로 기가바이트).<local-lock>(시스템별 상태).setup adopt가 모든 활성 대상 디렉토리에 생성하는magpie-*심볼릭 링크 —.agents/skills/의 표준 링크(gitignore된 스냅샷을 대상으로 함)와.claude/skills//.github/skills// 홀드아웃의 릴레이(표준 항목을 대상으로 함) — 모두 새 클론에서 끊어집니다. 각 디렉토리에서 무시되지 않는 유일한 예외는magpie-setup입니다.
커밋됨: 이 스킬(setup, 표준 .agents/skills/magpie-setup/ 및 그 릴레이), <committed-lock>, .apache-magpie-overrides/ 디렉토리, .gitignore 항목 자체, adopt 하위 액션이 만드는 모든 프로젝트 문서 업데이트.
황금 규칙 5 — .agents/skills/는 표준이며; 다른 모든 것은 그냥 릴레이됩니다. 채택 프로젝트가 이전에 .claude/skills/ 또는 .github/skills/를 어떻게 구성했든, adopt는 항상 동일한 방식으로 프레임워크를 연결합니다: 표준 magpie-* 링크는 .agents/skills/에 있고, 다른 모든 활성 대상(.claude, .github, 홀드아웃)은 스킬별 릴레이 심볼릭 링크를 받아 표준 항목을 다시 가리킵니다(.claude/skills/magpie-<n> → ../../.agents/skills/magpie-<n>). 해당 디렉토리에 있는 채택자의 기본(비-magpie-) 스킬은 그대로 둡니다. agents.md 참조.
황금 규칙 6 — 이 스킬은 복사하고 나머지는 심볼릭 링크합니다. 모두 magpie- 접두사 아래. 이 스킬(소스 skills/setup/)은 채택자 저장소로 복사되는 유일한 프레임워크 스킬입니다 — 표준 .agents/skills/magpie-setup/으로 커밋되고, .claude/skills/magpie-setup 및 .github/skills/magpie-setup으로의 릴레이 심볼릭 링크도 커밋됩니다. 다른 모든 프레임워크 스킬은 심볼릭 링크됩니다(표준 링크는 gitignore된 스냅샷을 가리키고, 릴레이 포함), 각각 magpie-<framework-skill> (예: magpie-security-issue-import → <snapshot-dir>/skills/security-issue-import/)로 명명됩니다. magpie- 접두사는 모든 프레임워크 스킬에 네임스페이스를 제공하여 채택자의 고유 스킬과 충돌하지 않도록 합니다. 복사와 심볼릭 링크를 혼합하는 것(예: 보안 스킬을 복사)은 유지보수 위험을 만듭니다: 복사본은 프레임워크의 진리 소스에서 벗어나며, 드리프트 감지 메커니즘(프레임워크 버전이 <snapshot-dir>의 것이라고 가정)이 조용히 잘못 적용됩니다.
황금 규칙 7 — 에이전트 재정의는 런타임에 읽힙니다. 재정의를 지원하는 모든 프레임워크 스킬은 실행을 시작할 때 .apache-magpie-overrides/<this-skill>.md에서 채택자별 지침을 확인하고 기본 동작을 실행하기 전에 적용합니다. 재정의 파일은 에이전트가 해석하는 일반 마크다운입니다 — 템플릿 엔진이나 패치 도구가 없습니다. 계약은 docs/setup/agentic-overrides.md를 참조하세요.
황금 규칙 8 — 두 패밀리는 항상 설치되며; 나머지는 옵트인입니다. 두 스킬 패밀리는 모든 adopt/upgrade/worktree-init 실행 시 조건 없이 연결되며 사용자에게 절대 묻지 않습니다:
setup-*— 소스 이름이setup-으로 시작하는 모든 프레임워크 스킬(부트스트랩setup자체 제외. 이는 규칙 6에 따라magpie-setup으로 복사되고 심볼릭 링크되지 않음). 구체적으로:setup-isolated-setup-install,setup-isolated-setup-update,setup-isolated-setup-verify,setup-override-upstream,setup-shared-config-sync, 그리고 프레임워크가 미래에 추가할setup-*스킬 — 각각magpie-setup-*로 심볼릭 링크됨.list-*— 발견 패밀리; 소스 이름이list-로 시작하는 모든 프레임워크 스킬. 현재는list-skills만(magpie-list-skills로 심볼릭 링크됨); 이 접두사는 프레임워크가 di...
...(잘림, 원문이 잘려서 제공됨)