시작하기: 아무것도 없는 상태에서 동작하는 하니스까지

이 튜토리얼은 첫 Apothem 설정의 처음부터 끝까지를 안내합니다. 아무것도 설치되지 않은 상태에서 시작하여, 직접 작성한 프로필에서 생성되고, 검증되고, 동작이 확인된 실제 하니스 구성으로 마무리합니다. 약 15분을 예상하세요. 아래의 모든 명령은 실제 명령이며 복사하여 붙여넣어 실행할 수 있습니다.

이 튜토리얼을 마치면 다음을 완료하게 됩니다.

1. 스크립트 설치 프로그램으로 Apothem 설치.
2. 모든 하니스를 구동하는 공유 프로필 편집.
3. 하니스의 네이티브 구성 머티리얼라이즈.
4. 그 구성을 검증하고 동작하는 첫 실행 확인.

이 튜토리얼 전반에서 예시 하니스로 Claude Code를 사용합니다. 설치 프로그램의 기본값이기 때문입니다. 같은 단계가 지원되는 모든 하니스에 적용됩니다. 하니스 목록에 이르면 이름을 바꾸세요.

먼저 필요한 것Copy Anchor Link

• Unix 계열 셸(macOS, Linux, 또는 WSL). PowerShell 설치 프로그램은 Windows를 다루며, 이 튜토리얼은 bash 경로를 보여 줍니다.
• PATH에 있는 Python 3.10 이상. python3 --version으로 확인하세요.
• 엔진이 인터프리터에서 임포트하는 두 런타임 라이브러리인 click과 rich. 나머지 스택(pyyaml, jsonschema)은 트리에 벤더링되어 있으므로 이 두 라이브러리만 임포트할 수 있으면 됩니다. click 또는 rich가 없으면 설치 프로그램이 중단되고 설치 명령을 출력합니다. 한 줄 명령은 스크립트를 bash로 파이프하므로 프롬프트를 띄울 수 없습니다. APOTHEM_AUTO_INSTALL_DEPS=1을 설정하거나(예: curl -fsSL https://apothem.ahmedgad.com/install.sh | APOTHEM_AUTO_INSTALL_DEPS=1 bash), 두 패키지를 먼저 설치하세요.

Apothem은 게시된 패키지가 아니라 번들된 소스 트리로 배포되므로 pip install 단계가 없습니다. 설치 프로그램은 트리를 클론하고 그 트리에서 엔진을 직접 실행합니다.

1단계 — Apothem 설치Copy Anchor Link

네트워크 설치 프로그램을 실행하세요.

curl -fsSL https://apothem.ahmedgad.com/install.sh | bash

설치 프로그램은 다음 단계를 수행합니다.

1. 전제 조건 확인. 설치 프로그램은 실제 Python 3.10 이상 인터프리터를 찾고, 두 런타임 라이브러리(click과 rich)를 임포트할 수 있는지 확인합니다. 하나라도 없으면 그 이름을 알려 주고 중단한 뒤 설치 명령을 출력합니다. 파이프로 실행하면 프롬프트를 띄울 수 없으므로, 묻지 않고 설치하려면 APOTHEM_AUTO_INSTALL_DEPS=1을 설정하세요.
2. 소스 배치. 번들된 트리는 ~/.apothem에 클론됩니다(APOTHEM_HOME 환경 변수로 재정의). 다시 실행하면 기존 클론을 중복으로 만드는 대신 그 클론에서 릴리스 태그를 체크아웃합니다.
3. 프로필 부트스트랩. 아직 프로필이 없으면 설치 프로그램은 예시 프로필을 ~/.config/apothem/profile.yaml에 복사하고, 같은 실행에서 그 프로필로 Claude Code를 설치하고 검증하며, 신원 필드가 자리표시자라고 경고합니다.

환경 변수로 설치를 조정할 수 있습니다. 가장 자주 사용할 만한 변수는 다음과 같습니다.

# Install a different user-scope harness and name the profile path explicitly.
# Put the variables on the `bash` side of the pipe: a variable placed before
# `curl` reaches only curl, not the installer.
curl -fsSL https://apothem.ahmedgad.com/install.sh | \
  APOTHEM_HARNESS=codex \
  APOTHEM_PROFILE="$HOME/.config/apothem/profile.yaml" \
  bash

설치 프로그램은 사용자 범위 하니스만 설치합니다. 프로젝트 범위 하니스는 그 뒤에 프로젝트를 지정하여 설치하세요.

apothem install --harness cursor --project /path/to/project

그 밖에 인식되는 변수는 APOTHEM_REPO와 APOTHEM_REF입니다. 이 변수들은 어떤 원격 저장소를 클론하고 어떤 git ref를 체크아웃할지 정합니다. 설정하지 않으면 서명된 최신 릴리스 태그를 해석하고 검증합니다. 특정 태그로 고정하려면 그 태그를, 움직이는 브랜치를 쓰려면 main을 설정하세요(브랜치는 서명된 태그가 아니므로 APOTHEM_ALLOW_UNVERIFIED=1도 필요합니다). APOTHEM_ALLOW_UNVERIFIED=1은 태그 서명 검증 실패를 경고로 낮추고, main 같은 태그가 아닌 ref를 허용합니다. APOTHEM_SOURCE는 클론 대신 기존 로컬 체크아웃을 사용합니다. APOTHEM_SKIP_VERIFY=1은 설치 후 검증을 건너뛰는데, 이 튜토리얼에서는 그 검증을 실행하려 하므로 설정하지 않은 채로 두세요.

설치 프로그램은 전체 실행을 마치면 엔진을 호출하는 방법을 보여 주는 배너를 출력합니다. 설치 프로그램은 PATH에 apothem 심(shim)을 배치하므로(POSIX: $HOME/.local/bin, Windows: %LOCALAPPDATA%\Microsoft\WindowsApps), 그 디렉터리가 PATH에 있으면 엔진을 직접 실행합니다.

apothem <command>

심을 배치할 수 없었거나 심의 디렉터리가 아직 PATH에 없으면, 배너는 심이 필요 없는 자체 완결형 대체 명령을 출력합니다.

PYTHONPATH="$HOME/.apothem/src" python3 -m apothem <command>

이 튜토리얼의 나머지 부분은 apothem <command>로 표기합니다. 대체 형식을 사용한다면 설치 프로그램 배너가 출력한 정확한 접두사를 앞에 붙이세요.

2단계 — 프로필을 자신의 것으로 만들기Copy Anchor Link

~/.config/apothem/profile.yaml에 있는 공유 프로필은 단일 진실 공급원입니다. 모든 하니스 어댑터가 이 프로필을 읽고 그로부터 해당 하니스의 네이티브 구성을 도출합니다. 한 번 편집하면 설치하는 모든 하니스가 일관성을 유지합니다.

엔진의 편집기나 아무 텍스트 편집기에서 여세요.

apothem profile edit

최소한의 유효한 프로필은 다음과 같습니다.

identity:
  name: "Example User"
preferences:
  style: "concise"
rules:
  - "Validate external input before writing files."

플레이스홀더 name을 자신의 이름으로 바꾸고, 모든 하니스가 적용하기를 원하는 규칙을 추가하세요. 예시 값은 가짜로 유지하세요. 프로필은 안전하게 공유할 수 있도록 만들어졌습니다.

엔진이 편집 내용을 문제없이 다시 읽는지 확인하세요.

apothem profile show --json

YAML 형식이 잘못되었다면 여기서 드러납니다. 다음으로 넘어가기 전에 수정하고 다시 실행하세요.

3단계 — 하니스 구성 머티리얼라이즈Copy Anchor Link

1단계에서 프로필을 만들었다면, 설치 프로그램이 이미 자리표시자 신원으로 Claude Code를 설치한 상태입니다. 2단계에서 프로필을 편집한 다음, 다음 명령으로 신원을 적용하세요:

apothem update --harness claude-code

apothem install --harness claude-code

이 명령은 프로필을 읽고 Claude Code의 네이티브 구성을 씁니다. 대상으로 지정할 수 있는 모든 하니스를 보려면 다음을 실행하세요.

apothem harnesses list

일부 하니스는 사용자 범위가 아니라 프로젝트 범위이며, 이러한 하니스에는 어댑터가 어디에 쓸지 알 수 있도록 --project 경로가 필요합니다.

apothem install --harness cursor --project .

4단계 — 검증하고 첫 실행 확인하기Copy Anchor Link

머티리얼라이즈는 이야기의 절반일 뿐입니다. 이제 구성이 올바르게 기록되었는지 확인하세요.

apothem verify --harness claude-code

verify는 하니스의 관리 대상 구성 파일이 존재하고 파싱되는지 확인합니다. --profile PATH를 추가하면, 설치된 파일이 그 프로필이 생성할 내용에서 벗어났을 때도 실패합니다. 깨끗한 실행은 머티리얼라이즈가 성공했음을 뜻합니다.

등록된 모든 어댑터에 걸쳐 머신 전체 상태 점검을 하려면 다음을 실행하세요.

apothem doctor

doctor는 설치된 모든 하니스를 점검하며(하니스는 검증을 통과해야 하고, 등록된 훅 명령이 시작되어야 합니다), 점검이 하나라도 실패하면 0이 아닌 코드로 종료합니다. 설치하지 않은 하니스는 목록에 표시되지만 점검을 실패시키지 않으므로, 설정 스크립트에서 유용한 게이트가 됩니다.

첫 실행. 방금 구성한 하니스(이 예에서는 Claude Code)를 열고 아무 프로젝트에서나 세션을 시작하세요. 프로필에 작성한 규칙과 선호 설정이 이제 그 도구 동작의 일부입니다. 이것이 동작하는 첫 실행입니다. 2단계에서 편집한 프로필이 실제 세션을 형성하고 있습니다.

만든 것Copy Anchor Link

빈 머신에서 시작하여 Apothem을 설치하고, 공유 프로필을 작성하고, 그 프로필에서 하니스의 네이티브 구성을 머티리얼라이즈하고, 결과를 검증하고, 동작함을 확인했습니다. 프로필은 계속 남는 아티팩트입니다. 한 번 변경한 다음 apothem update --harness <name>을 다시 실행하면 그 변경 사항을 어느 하니스에든 반영할 수 있습니다.

다음 단계로Copy Anchor Link

• 다른 도구 추가하기. 하니스 목록은 지원되는 모든 플랫폼과 그 어댑터 이름을 다룹니다. 새 --harness로 3단계를 반복하세요.
• 한 가지 작업을 더 깊이 다루기. 하우투 레시피는 하니스 추가, 프로필 편집, 설치 프로그램 구동을 다룹니다. 사용 가이드는 규칙 작성, 플랜 작성, 적합성 게이트 실행을 다룹니다.
• 세부 사항 찾아보기. 레퍼런스는 각 아티팩트 클래스와 프로필 스키마를 문서화하며, CLI 레퍼런스는 모든 명령을 다룹니다. 각 어댑터는 하니스 아래에 자체 페이지가 있습니다.
• 세션보다 오래 지속되는 작업 계획하기. 재개 가능한 계획은 Apothem이 장기 실행 작업을 프로젝트 로컬 .apothem/plans/ 스위트로 외부화하여, 어느 머신의 새 세션이든 그 작업을 그 자리에서 재개하게 하는 방식을 설명합니다.

권장 다음 단계Copy Anchor Link

하니스를 더 추가하기 전에 apothem doctor를 실행하여 설정을 확인하세요. 이 명령은 등록된 모든 어댑터의 상태를 보고하므로, 방금 설치한 하니스는 정상으로, 나머지는 아직 설치되지 않음으로 표시됩니다.