paperclip 딥다이브
— AI 직원들의 업무·권한·비용을 지키는 회사 운영 서버

1프로젝트 한줄 요약

paperclip은 여러 AI 에이전트의 업무 배정·실행·검토·비용을 한곳에서 관리하는 운영 플랫폼입니다. 브라우저에서 회사를 만들고 목표와 프로젝트를 연결한 뒤, 에이전트에게 업무를 배정합니다. 서버는 실행 가능한지 확인하고 적절한 실행 환경으로 보내며, 결과와 사용량을 기록합니다.

독자가 가장 먼저 기억할 문장은 이것입니다. 에이전트의 추론 능력보다, 여러 실행이 함께 일할 때 지켜야 할 규칙을 설계하는 저장소입니다. 모델이 답변을 만드는 내부 알고리즘보다 “이 업무를 지금 시작해도 되는가”, “중지 뒤에 누가 정리하는가”라는 질문이 코드의 중심에 있습니다.

1-1. 화면에서 보는 것과 서버가 책임지는 것

회사·업무·실행을 분리해 두면 하나의 업무를 여러 차례 재시도하더라도 업무 자체를 복제할 필요가 없습니다. packages/db/src/schema/issues.ts와 heartbeat_runs.ts를 나란히 읽으면 이 차이가 드러납니다. 업무는 “끝내야 할 것”, 실행은 “그 일을 하려고 시도한 한 번”입니다.

2왜 주목받는가

2-1. 터미널 여러 개로 관리하기 어려워지는 순간

에이전트 하나를 쓸 때는 대화창만 있어도 충분할 수 있습니다. 하지만 조사 담당, 구현 담당, 검토 담당이 동시에 움직이면 담당자·진행 상태·승인·비용을 사람이 따로 맞춰야 합니다. README는 이 문제를 조직도, 목표, 예산, 거버넌스라는 회사 운영 개념으로 설명합니다.

이 제품 구성이 관심을 모았을 가능성은 높습니다. 다만 트렌딩 순위만으로 유입의 원인을 입증할 수는 없습니다. 2026-10-23 GitHub 기준 Monthly #1, 스타 106,337개, 포크 17,680개는 관심의 규모를 보여 줍니다. 아래의 주목 요인은 README의 제품 방향과 구현된 기능을 바탕으로 한 해석입니다.

이 저장소의 강점은 서로 다른 에이전트를 같은 업무·권한·비용 체계 안에서 운영하게 해 준다는 점입니다. 모델 성능이 같더라도 운영 규칙을 공유하면 사람이 결과를 추적하고 개입하기 쉬워집니다.

2-2. 비슷한 도구와 비교하면 어디에 놓이는가

비교 기준은 각 도구의 중심 추상화입니다. LangGraph 공식 개요 문서는 상태를 갖는 그래프와 영속 실행을, CrewAI 공식 소개는 에이전트 팀과 Flow를 설명합니다. 이들도 영속성·감시·사람의 개입을 지원하는 생태계가 있으므로, 특정 기능의 독점 여부나 성능 순위를 뜻하는 표는 아닙니다.

2-3. 인기가 곧 쉬운 입문 난이도를 뜻하지는 않는다

공개 프레임워크 하나를 감싼 작은 예제가 아닙니다. 웹 화면, 인증, 데이터베이스, 원격 실행, 플러그인, 복구 로직까지 있습니다. TypeScript·TSX만 합쳐 약 260.8만 줄이며 테스트·스토리·생성 파일도 포함한 물리적 줄 수입니다. 초보자는 전체를 정독하기보다 4절의 한 가지 요청 경로부터 따라가는 편이 좋습니다.

3기술 스택 전체 지도

아래 버전은 커밋 412914c 기준입니다. package.json의 ^는 허용 범위이고, pnpm-lock.yaml의 값은 그 시점에 기록된 해석 결과입니다. 의존성 선언의 버전 범위와 실제 잠금 버전을 구분해야 같은 환경을 설명할 수 있습니다.

3-1. 백엔드와 데이터 계층

packages/db/src/client.ts는 drizzle-orm/postgres-js와 postgres를 가져옵니다. server/src/index.ts는 연결 문자열이 있으면 외부 PostgreSQL을 쓰고, 없으면 embedded-postgres를 동적으로 불러옵니다. 내장 모드도 실제 PostgreSQL을 관리하는 구성이지 브라우저 안에서 동작하는 DB라는 뜻이 아닙니다. 단, authenticated·public 배포는 외부 PostgreSQL 연결 문자열이 필수입니다.

3-2. 프론트엔드

프론트 버전의 근거는 ui/package.json입니다. 같은 저장소의 Runner 개발 화면은 별도 package.json에서 다른 Vite 범위를 선언하므로, 특정 버전을 “저장소 전체가 공통으로 사용한다”고 일반화하면 안 됩니다.

3-3. 인프라·빌드·검증

pnpm-workspace.yaml은 서버·UI·CLI와 여러 패키지를 묶으면서 packages/plugins/sandbox-providers/**는 제외합니다. 해당 플러그인의 외부 의존성을 독립적으로 설치하려는 경계입니다. 또한 postgres·embedded-postgres 등에 패치를 적용합니다. 버전 숫자만 같아도 패치가 다르면 코드가 같지 않을 수 있습니다.

CI는 pr.yml에서 재사용 워크플로를 호출합니다. pr-trusted.yml의 정책 작업은 수동 잠금 파일 변경을 제한하고 의존성 해석을 검사합니다. 설치 액션은 고정 잠금 설치가 실패하면 잠금을 다시 해석하는 경로도 갖습니다. 따라서 잠금 파일은 중요한 근거이지만, 모든 빌드가 아무 조건 없이 동일한 의존성으로 끝난다는 증거는 아닙니다.

4아키텍처 심화 분석

4-1. 전체 시스템 구조

이 그림의 핵심 경계는 업무를 관리하는 서버와 실제로 도구를 실행하는 환경 사이입니다. 같은 컴퓨터에 둘 다 있을 수도 있고 원격으로 떨어져 있을 수도 있습니다. 경계가 나뉘면 네트워크 단절을 프로세스 종료로 오해하지 않는 설계가 필요해집니다.

서버의 시작점은 server/src/index.ts입니다. 설정과 DB를 준비하고 server/src/app.ts의 createApp()으로 HTTP 애플리케이션을 구성합니다. UI가 같은 주소에서 보이더라도 API·업무 서비스·실행 환경은 서로 다른 책임을 갖습니다.

4-2. 패턴 ① 조건부 갱신으로 업무 소유권 확보

POST /api/issues/:id/checkout은 에이전트가 업무를 가져가는 입구입니다. server/src/routes/issues.ts는 요청 검증, 접근 가능한 업무 조회, 프로젝트 중지 여부, 에이전트 본인의 ID인지 등을 확인한 뒤 svc.checkout()을 호출합니다.

// packages/shared/src/validators/issue.ts의 실제 입력 계약
export const checkoutIssueSchema = z.object({
  agentId: z.string().guid(),
  expectedStatuses: z.array(z.enum(ISSUE_STATUSES)).nonempty(),
});

서비스 구현은 server/src/services/issues.ts의 issueService(db)가 반환하는 checkout 메서드입니다. 회사 내 배정 가능 여부, 업무 트리의 중지 조건, 선행 업무의 해결 여부를 검사합니다. 그다음 예상 상태·담당자·실행 잠금 조건이 모두 맞는 행만 UPDATE합니다.

-- 실제 Drizzle 조건을 단순화해 풀어 쓴 학습용 SQL
UPDATE issues
SET assignee_agent_id = :agent_id,
    checkout_run_id = :run_id,
    execution_run_id = :run_id,
    status = 'in_progress'
WHERE id = :issue_id
  AND status IN (:expected_statuses)
  AND (assignee_agent_id IS NULL OR :same_run_assignee)
  AND (execution_run_id IS NULL OR execution_run_id = :run_id)
RETURNING *;

“먼저 조회했을 때 비어 있었다”는 사실만 믿으면 두 요청이 모두 성공할 수 있습니다. 이 코드는 갱신하는 순간에도 조건을 검사합니다. 다른 실행이 먼저 소유권을 잡으면 후속 갱신의 조건이 맞지 않습니다. 갱신 결과가 없을 때는 현재 상태를 다시 읽어 같은 실행의 재요청인지, 복구 가능한 오래된 잠금인지 등을 판별합니다.

복구·재요청 조건까지 해결되지 않으면 conflict("Issue checkout conflict", ...)로 끝납니다. 또한 assertCheckoutOwner()는 이후 변경에서도 소유권을 검사합니다. 잠금을 처음 잡았다는 이유로 모든 후속 행동을 영구 허용하지 않는 것이 중요합니다.

4-3. 패턴 ② 실행 조율과 제공자 구현을 분리

server/src/services/heartbeat.ts의 heartbeatService()는 실행 생명주기를 조립합니다. createHeartbeatQueue()가 대기열을, executeRunAttempt()가 실행 시도를, createHeartbeatRunCompletion()의 completeRun()이 완료 처리를 맡습니다.

executeHeartbeatRuntime()에는 native 실행과 legacy adapter 실행 경로가 함께 있습니다. native 경로는 executePaperclipNativeSession()에 위임하고, legacy 경로는 adapter.execute(...)를 호출합니다. 현재 코드를 옛날 어댑터 설명 하나로만 이해하면 Rust Runner 경로를 놓칩니다.

// packages/adapter-utils/src/types.ts의 계약 일부
export interface ServerAdapterModule {
  type: string;
  execute(ctx: AdapterExecutionContext): Promise<AdapterExecutionResult>;
  testEnvironment(ctx: AdapterEnvironmentTestContext): Promise<AdapterEnvironmentTestResult>;
  // 세션·모델·스킬 등 선택적 기능은 별도 필드로 선언
}

이것은 전략 패턴을 읽는 좋은 예입니다. 호출자는 공통 계약을 사용하고, 제공자별 명령과 결과 해석은 구현체가 맡습니다. AdapterExecutionResult는 종료 코드뿐 아니라 usage, costStatus, sessionParams 등도 표현합니다.

server/src/adapters/registry.ts는 구현을 등록하고 선택합니다. getServerAdapter()는 찾지 못할 때 process 어댑터로 대체하지만, requireServerAdapter()는 알 수 없는 유형을 오류로 처리합니다. 같은 레지스트리라도 호출자가 요구하는 실패 정책에 따라 함수가 다릅니다.

4-4. 패턴 ③ 영속 상태로 실행과 복구를 조율

실행 결과를 받았다는 사실과 프로세스 종료·비용 정산·파일 정리가 끝났다는 사실은 서로 다릅니다. heartbeat_runs에는 실행 상태 외에도 정산 대기 여부, 세션 ID, 로그 참조, 재시도 연결, 컨트롤러 소유권 관련 필드가 있습니다. 이런 구분이 있어야 재시작 뒤에 남은 의무를 판단할 수 있습니다.

Rust 구현은 packages/paperclip-runner/runner/crates/runner-core/src/durable/에 있습니다. 그 안의 state.rs에서 Command는 command_id와 controller_seq를 갖고, validate()는 스키마 버전·식별자·순번·페이로드 형태를 검사합니다.

// durable/state.rs의 명령 필드 일부
pub struct Command {
    pub schema: String,
    pub command_id: String,
    pub controller_seq: u64,
    // 명령 유형·시각·사전 조건·페이로드가 이어짐
}

같은 파일의 save()는 상태를 직렬화하고 임시 파일에 쓴 다음 sync_all(), fs::rename()을 거쳐 상태 파일을 교체합니다. Unix에서는 상위 디렉토리도 동기화합니다. 파일에 JSON을 썼다는 사실과 장애 후에도 복구할 수 있게 저장했다는 사실의 차이를 보여 줍니다.

서버의 예약 작업도 메모리 타이머 하나에 모든 책임을 맡기지 않습니다. createWorkScheduler()는 이름별 기한을 Map에 넣고 가장 가까운 기한에 타이머를 맞춥니다. createDeliveryWorkCoordinator()는 중복 실행을 조정하고 실패 후 재시도와 DB 작업 신호를 연결합니다. 다만 이 스케줄러 자체는 프로세스 메모리이므로, 재시작 복구에는 영속 데이터에서 할 일을 다시 구성하는 경로가 필요합니다.

예산 검사도 실행 권한의 일부다

server/src/services/budgets.ts의 budgetPoliciesForRun()은 회사·에이전트·프로젝트에 해당하는 정책을 고릅니다. recheckAdmittedRunBudgetReadOnly()는 실행이 보유한 예약과 현재 지출을 다시 검사합니다. 미정산 실행이나 가격을 확정할 수 없는 사용량도 정책에 따라 실행을 막을 수 있습니다.

이 재검사는 이미 승인된 실행의 인계 단계에 붙는 읽기 전용 보완 검사입니다. 예산 초과 시 중지 전달과 정산은 다른 경로의 책임입니다. 따라서 “예산 상한이 있으니 외부 제공자의 청구액도 언제나 한 푼도 넘지 않는다”고 해석해서는 안 됩니다.

4-5. 패턴 ④ 알림으로 화면을 갱신하되 원본 데이터는 다시 확인

server/src/services/live-events.ts의 publishLiveEvent()는 회사별 EventEmitter 알림을 발행합니다. server/src/realtime/live-events-ws.ts가 /api/companies/:id/events/ws 연결을 처리하며 접근 권한을 검사합니다. 회사 ID가 URL에 있다는 사실만으로 구독 권한이 생기지는 않습니다.

클라이언트의 ui/src/context/LiveUpdatesProvider.tsx는 소켓을 공유합니다. applyRunLifecycleToCompanyLiveRuns()는 기존 실행의 상태를 캐시에 반영하고, 종료된 실행을 활성 목록에서 제거합니다. 반면 필요한 데이터가 부족한 경우에는 다시 조회합니다.

5디렉토리 구조 해부

5-1. 처음 읽을 때의 추천 순서

1. packages/db/src/schema/issues.ts: 업무가 어떤 데이터를 갖는지 먼저 봅니다.
2. packages/shared/src/validators/issue.ts: 외부 요청에서 허용하는 형태를 봅니다.
3. server/src/routes/issues.ts: /issues/:id/checkout을 찾아 입구를 봅니다.
4. server/src/services/issues.ts: checkout: async를 찾아 실제 변경 조건을 봅니다.
5. ui/src/context/LiveUpdatesProvider.tsx: 변경이 화면에 어떻게 반영되는지 봅니다.

서비스 파일은 매우 크므로 첫 줄부터 읽으면 맥락을 잃기 쉽습니다. 함수 이름으로 이동하고, 인자와 반환값을 기록한 뒤, 필요한 호출만 확장하세요. 폴더 전체를 이해하는 것보다 “업무 하나의 소유권이 바뀌는 경로”를 설명할 수 있는 것이 먼저입니다.

5-2. 직접 집계한 코드와 지원 파일의 규모

커밋 412914c의 Git 추적 파일에서 위 확장자의 줄바꿈을 합산한 값입니다. 빈 줄·주석·테스트·스토리·생성 코드가 포함되며, Markdown 등 문서 형식·JSON·잠금 파일은 제외했습니다. 의존성·빌드·캐시 디렉토리와 심볼릭 링크도 제외했습니다. 순수 구현량이나 기능 품질 점수로 읽으면 안 됩니다.

같은 확장자 기준으로 server/ 약 122만 줄, ui/ 약 67만 줄, packages/ 약 71만 줄, cli/ 약 4.5만 줄입니다. packages/db/src/migrations/에는 SQL 파일이 373개 있습니다. 이 숫자는 스키마 변화의 규모를 가늠하게 해 주지만, 이 파일 집계만으로 전체 개발 기간의 커밋 수나 기여 비중까지 알 수는 없습니다.

6학습 포인트 (기술별)

6-1. TypeScript + Zod: 타입과 입력 검증의 경계

TypeScript 타입은 개발 중 실수를 줄여 주지만 인터넷에서 들어온 JSON을 자동으로 검사하지 않습니다. server/src/middleware/validate.ts의 validate(schema)는 schema.parse(req.body)를 호출해 실제 값을 검사하고 다음 미들웨어로 넘깁니다.

// packages/shared/src/validators/issue.ts의 실제 타입 추론
export type CheckoutIssue = z.infer<typeof checkoutIssueSchema>;

// 읽기 실험: 아래 두 JSON을 스키마와 대조해 보세요.
{ "agentId": "올바른 UUID가 아님", "expectedStatuses": ["todo"] }
{ "agentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "expectedStatuses": [] }

배울 것: 하나의 스키마에서 검증과 타입을 함께 정의하는 방식입니다. 작은 실습: 위 두 요청이 각각 어느 조건에서 실패하는지 적고, “올바른 UUID와 비어 있지 않은 상태 배열”로 고쳐 보세요. 그다음 입력 형태가 맞아도 권한과 업무 상태 검사는 따로 필요하다는 점까지 설명해 봅니다.

6-2. PostgreSQL + Drizzle: SQL을 숨기지 않는 ORM 읽기

pgTable()은 테이블을 TypeScript로 표현하고, and()·eq()·isNull()은 SQL 조건을 구성합니다. ORM을 사용해도 조건부 UPDATE, 외래 키, 인덱스, 트랜잭션의 의미를 알아야 합니다. issues.ts에는 companyId와 상태를 묶은 인덱스도 있습니다.

배울 것: 데이터가 같은 회사에 속한다는 관계와, 요청자가 그 회사에 접근할 수 있다는 권한은 별도라는 점입니다. 작은 실습: 업무 목록을 “회사 + 담당자 + 상태”로 찾는다고 가정하고, 스키마의 assigneeStatusIdx가 어떤 조회를 돕는지 설명해 보세요.

6-3. React + TanStack Query: 화면 상태와 서버 상태

창이 열렸는지 같은 UI 상태와, 현재 업무가 진행 중인지 같은 서버 상태는 다릅니다. 후자는 다른 에이전트가 바꿀 수 있습니다. 이때 화면 안의 변수 하나만 바꾸면 다른 목록이나 상세 화면이 오래된 값을 갖게 됩니다.

배울 것: LiveUpdatesProvider.tsx에서 setQueryData()와 invalidateQueries()의 역할을 비교하세요. 전자는 아는 값을 즉시 반영하고, 후자는 필요한 데이터를 서버에서 다시 확인하도록 합니다. 작은 실습: 종료 이벤트를 두 번 받았을 때 활성 실행 목록에서 같은 실행을 제거해도 괜찮은 이유를 써 봅니다.

6-4. 어댑터 계약: “성공”보다 풍부한 결과 모델

packages/adapter-utils/src/types.ts의 AdapterExecutionResult에는 usageBasis가 per_run인지 session_cumulative인지 나타내는 필드가 있습니다. 세션을 재사용했다고 사용량까지 누적 값이라고 추정해서는 안 된다는 주석도 있습니다.

배울 것: 외부 도구의 결과를 내부 계약으로 바꿀 때 정보의 기준도 함께 전달해야 합니다. 작은 실습: costStatus의 reported·estimated·unpriced를 한국어로 설명해 보세요. 가격을 알 수 없는 결과를 비용 0으로 취급하면 어떤 문제가 생길지도 적습니다.

6-5. Rust + 파일 저장: 안전하게 남기는 상태

packages/paperclip-runner/runner/crates/runner-core/src/durable/state.rs에서 Command::validate()와 save()를 읽습니다. Rust 문법을 모두 몰라도 Result가 실패를 표현하고, ?가 오류를 호출자에게 전달한다는 정도부터 시작할 수 있습니다.

배울 것: 상태 저장에 크기 제한·임시 파일·동기화·교체가 필요한 이유입니다. 작은 실습: “임시 파일을 쓰다가 종료”, “교체 직전 종료”, “교체 뒤 종료”를 나누고, 각 경우에 이전 파일과 새 파일 중 무엇을 읽을 수 있어야 하는지 표로 정리하세요. 실제 파일시스템의 보장은 별도 검증 대상입니다.

6-6. 원격 파일 전달: 경로보다 소유자와 내용을 확인

server/src/services/native-runtime/native-runner-file-handoff.ts의 readVerifiedWorkspaceFile()는 원격 실행이면 readRemoteTaskFile 또는 readRemoteWorkspaceFile에 읽기를 위임합니다. 받은 바이트 수와 SHA-256도 확인합니다.

로컬 경로에서는 작업 경계 밖 이동과 심볼릭 링크를 검사합니다. 배울 것: 원격 기기의 파일을 서버의 같은 문자열 경로에서 찾으면 안 된다는 점입니다. 작은 실습: native-runner-file-handoff.test.ts에서 원격 읽기와 해시 불일치 사례를 찾아, 경로 검사와 내용 검사가 각각 방어하는 실패를 구분합니다.

6-7. 테스트와 CI: 검증이 증명하는 범위를 읽기

server/src/__tests__/issues-checkout-wakeup.test.ts는 활성 실행 중인 에이전트의 자기 checkout이 추가 깨우기를 만들지 않는 규칙을 검사합니다. 이 테스트 하나가 DB의 모든 동시성까지 증명하지는 않습니다. 반면 budgets-service.test.ts는 내장 PostgreSQL을 이용하는 테스트 경로를 갖고 환경이 지원되지 않으면 건너뜁니다.

테스트를 읽을 때는 통과 여부와 함께 실제로 어떤 경계까지 실행했는지를 확인해야 합니다. 작은 실습: 함수 테스트·실제 DB 테스트·브라우저 테스트가 각각 발견할 수 있는 버그를 하나씩 적어 보세요. CI 파일을 읽으며 해당 검사가 어느 작업에서 실행되는지 연결하면 검증의 전체 지도가 생깁니다.

7하드웨어 / 시스템 요구사항

소스 전체 빌드까지 공부하려는 개인 환경은 4코어·RAM 16GB·여유 디스크 30GB 이상을 출발점으로 생각할 수 있습니다. 이것은 필자의 학습 환경 권장 추정이며 공식 최소 사양이나 측정 결과가 아닙니다. Rust 빌드 캐시와 에이전트별 저장소 사본이 쌓이면 이보다 더 필요할 수 있습니다.

필요한 자원은 에이전트 수보다 동시에 살아 있는 실행·프로세스·작업 사본의 수에 더 직접적으로 영향을 받습니다. 서버 메모리만 보지 말고 하위 프로세스, DB, 작업 디렉토리, 로그 저장량까지 함께 살펴야 합니다.

7-1. 기본 저장 경로와 운영 시 확인할 것

packages/shared/src/home-paths.ts는 기본 홈을 ~/.paperclip, 인스턴스 ID를 default로 정합니다. 기본 인스턴스 루트는 ~/.paperclip/instances/default이며 PAPERCLIP_HOME과 PAPERCLIP_INSTANCE_ID로 바꿀 수 있습니다.

외부 DB·객체 저장소·원격 작업 환경을 사용하면 데이터가 여러 곳에 나뉩니다. 따라서 기본 폴더 하나의 복사만으로 모든 구성의 완전한 복구가 된다고 가정하면 안 됩니다. 코드의 경로 기본값과 실제 배포 설정을 함께 보아야 합니다.

7-2. 실행 모드와 외부 연결

서버 설정의 기본 호스트는 127.0.0.1입니다. Docker 이미지는 HOST=0.0.0.0과 PAPERCLIP_DEPLOYMENT_MODE=authenticated, PAPERCLIP_DEPLOYMENT_EXPOSURE=private를 선언합니다. 로컬 실행과 컨테이너의 기본값을 혼동하지 마세요.

README의 소스 개발 시작 명령은 다음과 같습니다. 전체 빌드에는 Rust 등 추가 요구사항이 연결되며, 실제 에이전트 실행에는 해당 제공자의 인증과 실행 환경 준비가 필요합니다.

pnpm install
pnpm dev
# README 기준 UI와 API: http://localhost:3100
# 로컬 구성에서 외부 DB 연결 문자열이 없으면 내장 PostgreSQL을 준비

8직접 해볼 수 있는 실습 과제

앞의 두 과제는 애플리케이션을 띄우지 않고 시작할 수 있습니다. 실행 실험은 별도의 학습용 환경에서 가짜 에이전트와 연습용 데이터로 진행하세요. 좋은 실습의 완료 기준은 코드를 바꾼 양보다 실패 상황의 결과를 설명하고 확인할 수 있는가에 있습니다.

rg -n 'checkoutIssueSchema' packages/shared/src/validators/issue.ts
rg -n '/issues/:id/checkout' server/src/routes/issues.ts
rg -n 'checkout: async|Issue checkout conflict' server/src/services/issues.ts

type RunResult = { exitCode: number | null; timedOut: boolean };
type Executor = (task: string) => Promise<RunResult>;

const fakeExecutor: Executor = async (_task) => ({
  exitCode: 0,
  timedOut: false,
});

9관련 기술 심화 학습 로드맵

JavaScript 함수·배열·객체와 기본 HTML을 안다는 가정의 학습안입니다. 처음 보는 문법이 많으면 1~2주차를 늘려도 좋습니다. 매주 하나의 동작을 설명하는 작은 결과물을 남기면 큰 저장소를 이해한 범위가 눈에 보입니다.

앞의 3주는 데이터와 요청의 규칙을 이해하는 데 쓰고, 뒤의 3주는 여러 실행과 화면이 그 규칙을 공유하는 방법을 살펴봅니다. Rust 문법에서 막히면 파일 저장의 순서부터 한국어로 적은 뒤 각 호출에 대응시켜 보세요.

9-1. 공식 문서와 코드를 왕복하는 방법

• TypeScript 기본 타입에서 유니언을 읽고, 실행 결과의 선택적 필드와 비교합니다.
• Drizzle UPDATE 문서를 보고 .where()·.returning()이 SQL에서 무엇인지 적습니다.
• PostgreSQL 트랜잭션 격리를 읽으며 두 UPDATE가 경쟁하는 실험 결과를 해석합니다.
• React 입문 문서로 상태와 렌더링을 익힌 뒤, TanStack Query의 무효화로 서버 데이터 갱신을 연결합니다.
• Rust 공식 입문서의 소유권·오류 처리를 익히고 상태 저장 함수의 오류 전달을 따라갑니다.

10핵심 키워드 사전

한 단어가 서로 다른 계층에서 다른 뜻으로 쓰일 수 있습니다. 예를 들어 업무의 done, 실행의 succeeded, 파일 정리의 완료는 같은 상태가 아닙니다. 로그를 읽을 때는 “무엇의 상태인가”를 먼저 확인하세요.

11참고 링크

11-1. 공식 저장소·제품 문서

• paperclip 공식 저장소 · 코드·이슈·릴리스의 출발점
• 분석 기준 커밋의 전체 소스 · 최신 기본 브랜치와 구분
• README · 제품 방향·빠른 시작·텔레메트리 안내
• 공식 문서 · 설치·설정·운영 문서
• 어댑터 개요 · 연결 방식과 기능 범위
• 배포 모드 · 로컬·인증·노출 범위
• Docker 운영 안내
• v2026.1012.0 릴리스

11-2. 본문과 함께 열어 볼 핵심 소스

• 루트 package.json · 의존성 잠금 파일
• 서버 초기화 · 설정 기본값
• 업무 스키마 · 실행 스키마
• 업무 입력 검증 · HTTP 라우트
• 업무 서비스의 checkout·소유권 검사
• heartbeat 조율 코드 · 실행 위임 경로
• 어댑터 계약 · 구현 레지스트리
• 예산·예약·집행 서비스
• UI의 실시간 갱신과 재연결
• Rust의 영속 상태 저장 · Runner 구성·지원 환경
• 실행 환경의 파일 전달·검증
• 다단계 이미지 빌드 · PR 검증 워크플로

11-3. 관련 기술 공식 자료

• TypeScript 기본 타입 · React 학습 문서
• Drizzle의 조건부 UPDATE와 반환값 · PostgreSQL 트랜잭션 격리
• TanStack Query 캐시 무효화 · Rust 공식 입문서
• LangGraph 공식 개요 · CrewAI 공개 프레임워크 소개

현재 상태 (2026-10-23 확인)