시작하기: 영(zero)에서 동작하는 하니스까지

이 튜토리얼은 당신의 첫 Apothem 설정 전체를 안내합니다. 아무것도 설치되지 않은 상태에서 시작해, 실제 하니스 구성 — 당신이 작성한 프로필에서 생성되고, 검증되고, 동작이 확인된 것 — 으로 끝납니다. 약 15분으로 잡으세요. 아래의 각 명령은 실제로 동작하며 복사·붙여넣기할 수 있습니다.

끝날 때쯤에는 다음을 갖게 됩니다.

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

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

먼저 필요한 것

• Unix 계열 셸(macOS, Linux, 또는 WSL). PowerShell 설치 프로그램이 Windows를 커버하며, 이 튜토리얼은 bash 경로를 보여줍니다.
• PATH에 있는 Python 3.10 이상. python3 --version으로 확인하세요.
• 엔진이 인터프리터에서 임포트하는 두 개의 런타임 라이브러리: click과 rich. 나머지 스택(pyyaml, jsonschema)은 트리에 포함(vendored)되어 있으므로 이 두 개만 임포트 가능하면 됩니다. 설치 프로그램은 이들을 확인하고, 누락된 것을 알려 주며, 대신 설치하도록 제안하므로 확인하고 계속할 수 있습니다.

Apothem은 게시된 패키지가 아니라 패키징된 소스 코드 트리로 배포됩니다 — pip install 단계가 없습니다. 설치 프로그램이 트리를 클론하고 거기서 직접 엔진을 실행합니다.

1단계 — Apothem 설치

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

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에 복사한 다음, 계속하기 전에 멈춰서 편집하도록 요청합니다. 이는 의도적입니다. 샘플은 플레이스홀더 식별 정보를 사용하며, 어떤 하니스 구성을 쓰기 전에 그것을 당신의 것으로 만들어야 하기 때문입니다. 2단계에서 하겠습니다.

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

# Install a different harness as the default, and point at a project profile.
APOTHEM_HARNESS=cursor \
APOTHEM_PROFILE="$HOME/.config/apothem/profile.yaml" \
  curl -fsSL https://apothem.ahmedgad.com/install.sh | bash

인식되는 다른 변수로는 APOTHEM_REPO와 APOTHEM_REF(어떤 리모트를 클론하고 어떤 git ref를 다운로드할지. 미정의 시 서명된 최신 버전 태그를 해석·검증하며, 고정하려면 태그를, 움직이는 브랜치에는 main을 설정), APOTHEM_ALLOW_UNVERIFIED=1(태그 서명 검증 실패를 경고로 격하), APOTHEM_SOURCE(클론 대신 기존 로컬 체크아웃 사용), APOTHEM_SKIP_VERIFY=1(설치 후 검증 건너뜀. 이번에는 실행하고 싶으므로 미정의로 두세요)가 있습니다.

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

apothem <command>

shim을 배치할 수 없었거나 — 그 디렉터리가 아직 PATH에 없다면 — 배너는 shim이 필요 없는 자체 완결형 대체 방법을 출력합니다.

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

이 튜토리얼의 나머지에서는 apothem <command>라고 쓰겠습니다. 대체 형식을 쓰는 경우, 설치 프로그램 배너가 출력한 정확한 접두사를 각 명령 앞에 붙이세요.

2단계 — 프로필을 당신의 것으로 만들기

~/.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단계 — 하니스 구성 머티리얼라이즈

설치 프로그램은 1단계에서 이미 기본 하니스를 머티리얼라이즈했습니다. 이를 명시적으로 하려면 — 또는 두 번째 하니스를 머티리얼라이즈하려면 — install을 실행하세요.

apothem install --harness claude-code

이것은 당신의 프로필을 읽어 Claude Code의 네이티브 설정을 씁니다. 지정할 수 있는 각 하니스를 보려면 다음을 실행하세요.

apothem harnesses list

일부 하니스는 사용자 스코프가 아니라 프로젝트 스코프이며, 그것들은 어댑터가 어디에 쓸지 알도록 --project 경로가 필요합니다.

apothem install --harness cursor --project .

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

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

apothem verify --harness claude-code

verify는 하니스의 예상 설정 파일이 존재하고 프로필이 선언한 내용과 일치하는지 확인합니다. 깨끗한 실행은 머티리얼라이즈가 성공했음을 의미합니다.

등록된 각 어댑터에 대한 머신 전체 헬스 체크는 다음을 실행하세요.

apothem doctor

doctor는 각 어댑터의 설치 상태를 보고하며, 등록된 어댑터 중 하나라도 미설치로 보고하면 0이 아닌 코드로 종료합니다. 설정 스크립트에서 유용한 게이트입니다.

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

당신이 만든 것

빈 머신에서 시작해, Apothem을 설치하고, 공유 프로필을 작성하고, 거기서 한 하니스의 네이티브 설정을 머티리얼라이즈하고, 결과를 검증하고, 그것이 동작함을 확인했습니다. 프로필은 지속되는 아티팩트입니다. 한 번 변경하고 apothem update --harness <name>을 다시 실행해 그 변경을 임의의 하니스로 밀어내세요.

다음으로 어디로

• 다른 도구 추가하기. 하니스 목록은 지원되는 각 플랫폼과 그 어댑터 이름을 다룹니다. 새로운 --harness로 3단계를 반복하세요.
• 한 작업을 깊이 파고들기. 하우투 가이드는 규칙 작성, 플랜 생성, 적합성 게이트 실행을 위한 작업 중심 레시피입니다.
• 구체적 세부 사항 찾아보기. 레퍼런스는 각 어댑터, 프로필 스키마, 그리고 CLI의 모든 표면을 문서화합니다.
• 세션보다 오래 지속되는 작업 계획하기. 재개 가능한 계획은 Apothem이 장시간 작업을 프로젝트 로컬 .apothem/plans/ 스위트로 외부화하여 어떤 머신에서든 새 세션이 그 자리에서 재개하는 방식을 설명합니다.

권장 다음 단계

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