시작하기

SDK 설치, tiffy-app init으로 앱 폴더 만들기, 테스트와 검사 실행.

@tiffy/app-sdk는 지금 이 모노레포 안의 워크스페이스 패키지입니다(private: true, 버전 0.0.0). npm 레지스트리에 아직 게시되지 않았으므로 이 문서의 명령은 이 저장소 안에서 새 워크스페이스 패키지를 만들 때를 기준으로 씁니다.

SDK 의존성 추가
앱 폴더의 package.json에 @tiffy/app-sdk를 의존성으로 추가합니다. 모노레포 안에서는 워크스페이스 참조를 씁니다.
```
{
  "dependencies": {
    "@tiffy/app-sdk": "workspace:*"
  }
}
```
앱 폴더 만들기
SDK 패키지가 내놓는 tiffy-app 실행 파일로 새 앱 폴더를 만듭니다. init 뒤에는 역도메인 형태의 앱 id를 씁니다.
```
pnpm exec tiffy-app init com.example.myapp
```
현재 CLI는 init과 check 두 명령만 지원합니다. tiffy app publish와 run --sandbox는 마켓플레이스 제출과 함께 나올 예정입니다.

생성된 폴더 구조 확인

com.example.myapp/
  tiffy-app.json        매니페스트
  package.json           test, check, build 스크립트
  src/index.ts           defineApp({...}) 하나
  i18n/ko.json
  i18n/en.json
  surfaces/settings.json
  surfaces/home-card.json
  test/index.test.ts     vitest + createMockContext 예시
  icon.svg
  AGENTS.md
  CLAUDE.md

tools/, triggers/, schemas/ 폴더는 도구와 트리거를 추가하면서 직접 만듭니다. init은 빈 뼈대만 만듭니다.

테스트 실행
```
pnpm test
```
생성된 package.json의 test 스크립트는 vitest run --passWithNoTests입니다. test/index.test.ts는 createMockContext로 모의 ctx를 만들어 앱이 로드되는지만 확인하는 예시입니다.
검사 실행
```
pnpm check
```
check 스크립트는 tiffy-app check를 부릅니다. 매니페스트 스키마, 금지된 import, tools/triggers 키와 코드 대조, i18n 키 완비, surfaces 파일, 번들 크기, 아이콘·스크린샷 유무를 확인합니다.
출력은 이런 모양입니다.
```
src/tools/draftReply.ts
  error [forbidden_import]:3 금지된 import: '@tiffy/core'. @tiffy/app-sdk의 ctx만 쓴다.
i18n/en.json
  error [i18n_key_missing] en.json에 키 'mail.draftReply.title'가 없다 (ko.json에는 있다)

2 errors, 0 warnings
```
--json 옵션을 주면 { findings, errorCount, warningCount } 모양의 JSON을 출력합니다. errorCount가 0보다 크면 종료 코드가 1입니다.

지금 앱을 실제로 돌려 보려면: 내장 앱으로 등록하기

마켓플레이스 설치가 아직 없으므로, 지금 워커에서 앱을 실제로 실행해 보는 유일한 길은 내장(builtIn) 앱으로 등록하는 것입니다. 서드파티 코드를 임의로 실행하는 경로는 없습니다.

앱 id를 플랫폼의 내장 앱 registry에 등록하고, 앱 폴더의 번들 경로를 잇습니다. 워커의 호스트, 트리거 스케줄러, 도구 브리지가 전부 이 registry를 거쳐 번들을 찾습니다.
매니페스트의 builtIn: true를 켭니다.
영역이 쓰일 때마다 플랫폼이 registry가 아는 앱 id 중 아직 설치되지 않은 것을 찾아 자동으로 enabled 상태로 설치합니다. 이미 다 설치돼 있으면 조회 한 번으로 끝나서 매 메시지마다 불려도 가볍습니다.

이 절차를 거치면 /assist/apps에 앱이 뜨고, 사서 프로필이라면 agent_profiles.tools나 코드 프로필의 allowedTools(예: 사서는 notes.*)가 허용하는 한 그 도구를 대화 중에 부를 수 있습니다. 노트 앱을 예로 이 전체 경로를 따라가려면 노트 앱 뜯어보기 문서를 보세요.

AGENTS.md와 CLAUDE.md

init이 만드는 두 파일은 내용이 같습니다. 코드를 쓰는 에이전트(Claude Code, Codex 등)가 이 폴더를 열면 이 파일을 읽고 규칙을 따르라는 뜻입니다. 담긴 내용은 에이전트로 만들기 문서에서 자세히 다룹니다.

매니페스트를 채우는 방법은 매니페스트 문서를, 도구와 트리거 코드를 쓰는 방법은 ctx API 문서를 보세요.

앱 만들기 매니페스트

시작하기

지금 앱을 실제로 돌려 보려면: 내장 앱으로 등록하기

AGENTS.md와 CLAUDE.md

다음