turborepo-caching

turborepo-caching 스킬 개요

turborepo-caching가 하는 일

turborepo-caching은 Turborepo를 설정해 반복되는 빌드, 테스트, lint 실행을 다시 계산하지 않고 재사용하도록 만드는 실전형 스킬입니다. 여기서 핵심은 단순히 “캐싱을 켠다”가 아니라, 작업의 입력값, 출력물, 의존관계, 환경 변수 민감도를 충분히 정확하게 정의해 로컬과 CI 실행을 모두 더 빠르게 만들면서도 오래된 아티팩트를 잘못 제공하지 않도록 하는 데 있습니다.

이 스킬이 잘 맞는 대상

이 스킬은 Turborepo를 사용하는 JavaScript 또는 TypeScript 모노레포 팀이 아래와 같은 목적을 가질 때 가장 잘 맞습니다.

• 처음부터 turbo.json을 올바르게 구성하고 싶을 때
• CI와 여러 개발자를 위해 remote caching을 추가하고 싶을 때
• cache miss 때문에 느려지는 빌드를 줄이고 싶을 때
• 느슨하게 정의된 스크립트에서 재현 가능한 task pipeline으로 옮기고 싶을 때

특히 저장소 구조는 이미 잘 알고 있지만, 그것을 Turborepo의 캐시 모델로 어떻게 표현해야 할지 확신이 없을 때 유용합니다.

turborepo-caching 스킬을 설치할 만한 이유

turborepo-caching 스킬의 가치는 사용자가 가장 자주 틀리는 지점을 정리해준다는 데 있습니다.

• 어떤 파일을 outputs에 넣어야 하는지
• dependsOn에서 언제 ^build를 써야 하는지, 언제 task 단위 순서를 써야 하는지
• .env 파일과 환경 변수가 캐시 정확성에 어떤 영향을 주는지
• 왜 persistent task를 캐시 가능한 빌드 단계처럼 다루면 안 되는지
• CI/CD에서 로컬 캐싱과 remote caching을 어떻게 구분해 판단해야 하는지

그래서 단순한 “내 모노레포 최적화해줘” 같은 범용 프롬프트보다 더 실용적입니다. 이 스킬은 Turborepo의 실제 pipeline 동작 방식에 맞춰져 있기 때문입니다.

이 스킬이 대체하지 않는 것

이 문서는 Turborepo 전체 레퍼런스가 아니며, 저장소를 자동으로 분석해주지도 않습니다. 여전히 현재의 turbo.json, task 스크립트, 패키지 구조, 빌드 출력물을 직접 제공해야 합니다. 스택에서 Turborepo를 사용하지 않는다면 이 스킬은 적합하지 않습니다.

turborepo-caching 스킬 사용 방법

turborepo-caching 설치 맥락

업스트림 스킬은 SKILL.md 안에 전용 설치기를 제공하지 않으므로, wshobson/agents 저장소에 대해 평소 사용하던 스킬 설치 흐름을 사용한 뒤 에이전트 환경에서 turborepo-caching 스킬을 이름으로 호출하면 됩니다.

GitHub 소스를 지원하는 skill loader를 사용 중이라면 저장소 경로는 다음과 같습니다.

https://github.com/wshobson/agents/tree/main/plugins/developer-essentials/skills/turborepo-caching

먼저 읽어야 할 파일

다음 파일부터 확인하세요.

• plugins/developer-essentials/skills/turborepo-caching/SKILL.md

이 스킬은 자체 완결형입니다. 스킬 폴더 안에 별도의 rules/, resources/, helper script는 없으므로, 실제로 쓸 수 있는 핵심 가이드는 거의 이 파일 하나에 들어 있습니다.

turborepo-caching가 당신에게 요구하는 입력값

turborepo-caching을 제대로 활용하려면 막연한 목표만 주지 말고, 저장소에 대한 구체적인 사실을 에이전트에게 제공해야 합니다. 최소한 아래 정도는 있어야 실질적인 답변이 가능합니다.

• 현재 turbo.json
• 루트 package.json
• 대표적인 workspace package.json 1~2개
• 각 앱 또는 패키지에서 쓰는 빌드 도구 (Next.js, Vite, tsup, Jest 등)
• 어떤 task를 cacheable하게 만들고 싶은지
• dist/, build/, .next/, coverage 폴더 같은 예상 출력 디렉터리
• 사용하는 CI 제공자와 remote caching 필요 여부

이 정보가 없으면 에이전트는 결국 범용 템플릿 수준의 답밖에 만들 수 없습니다.

애매한 목표를 강한 프롬프트로 바꾸는 법

약한 프롬프트:

Help me optimize Turborepo caching.

더 강한 프롬프트:

Use the turborepo-caching skill to review my monorepo pipeline. I have apps/web with Next.js, packages/ui with tsup, and packages/config with TypeScript build scripts. Here is my current turbo.json and package scripts. I want faster CI builds, safe remote caching, and fewer cache misses when only UI code changes. Propose a revised turbo.json, explain each outputs entry, identify env vars that should affect cache keys, and call out any tasks that should not be cached.

이 프롬프트가 더 잘 작동하는 이유는 결과물 형태를 구체적으로 요청하고, 의존 그래프를 제공하며, 성공 기준까지 분명히 정의하기 때문입니다.

이런 결과물을 명시적으로 요청하세요

turborepo-caching 스킬은 아래 산출물 중 하나 이상을 요청할 때 가장 유용합니다.

• 수정된 turbo.json
• task별 cacheability 검토
• outputs 감사
• 환경 변수 감사
• CI remote caching 설정 가이드
• cache miss 디버깅 체크리스트

이렇게 요청하면 답변이 광범위한 아키텍처 이야기로 퍼지지 않고, 실제로 적용 가능한 설정 중심으로 좁혀집니다.

turborepo-caching의 일반적인 사용 워크플로

실무적으로는 아래 흐름이 가장 효과적입니다.

1. 현재 모노레포 구조와 스크립트를 공유합니다.
2. 에이전트에게 task를 build, test, lint, dev, persistent task로 분류하게 합니다.
3. turbo.json 초안을 만들거나 기존 파일을 수정하게 합니다.
4. 모든 outputs, dependsOn, inputs, env 관련 선택에 대해 근거를 설명하게 합니다.
5. 로컬에서 task를 실행하고 cache hit/miss를 비교합니다.
6. 로그나 예외 케이스를 들고 다시 와서 2차 검토를 받습니다.

검토 단계는 중요합니다. 캐싱 실패는 대개 출력물에 대한 잘못된 가정이나 드러나지 않은 입력값 때문에 발생합니다.

저장소에서 집중해서 봐야 할 개념

이 스킬은 사용 시 아래 핵심 개념을 중심에 두고 있습니다.

• dependsOn은 실행 순서와 상위 빌드 관계를 제어합니다
• outputs는 Turborepo가 캐시에서 복원할 수 있는 대상을 결정합니다
• inputs와 global dependency는 어떤 조건에서 캐시 결과가 무효화되는지 결정합니다
• persistent는 장시간 실행되는 task를 위한 것이며 모델링 방식도 달라져야 합니다

프롬프트에서 이 부분을 짚지 않으면, 에이전트가 느린 빌드의 진짜 원인을 놓칠 수 있습니다.

좋은 turborepo-caching 검토 요청 예시

아래처럼 요청해 보세요.

Apply the turborepo-caching skill to this turbo.json. Tell me which tasks are unsafe to cache, whether .next/** is too broad for my Next.js app, whether !.next/cache/** should be excluded, and whether my .env.local and VERCEL_URL should be in globalDependencies or globalEnv. Then propose a corrected config.

이런 요청은 단순히 “best practices 알려줘”라고 하는 것보다 훨씬 강합니다. 정확성을 좌우하는 설정 포인트를 직접 겨냥하기 때문입니다.

요청 전에 저장소에서 직접 점검할 것

turborepo-caching 스킬을 호출하기 전에 아래를 먼저 확인하세요.

• 각 패키지가 아티팩트를 안정적인 폴더에 기록하는지
• 생성 파일이 눈에 띄는 output 폴더 밖에 생기지는 않는지
• 빌드 스크립트가 .env 또는 CI 전용 변수를 읽는지
• 테스트가 snapshot, report, coverage 출력물을 생성하는지
• 비결정적인 스크립트가 있는지

출력물이 불안정하거나 입력값이 숨어 있으면, turbo.json이 유효해도 캐싱이 고장난 것처럼 보일 수 있습니다.

설치와 도입에서 자주 막히는 지점

가장 큰 장애물은 거의 아무 맥락도 주지 않은 채 스킬이 task graph를 알아서 추론해주길 기대하는 것입니다. 두 번째는 모든 스크립트를 cacheable하다고 보는 태도입니다. 개발 서버, watch mode, 기타 persistent process는 보통 별도로 다뤄야 합니다. 세 번째는 환경 변수가 cache key를 바꿀 수 있다는 점을 놓치는 것입니다. 특히 프런트엔드 빌드에서는 더 그렇습니다.

turborepo-caching 스킬 FAQ

turborepo-caching는 초보자에게도 유용한가요

네. 이미 Turborepo 기반 저장소를 쓰고 있거나, Turborepo 사용을 확정한 상태라면 초보자에게도 유용합니다. 특히 초보자가 자주 헷갈리는 outputs, dependsOn, env 기반 무효화를 구조적으로 정리해줍니다. 반대로 아직 어떤 모노레포 도구를 도입할지 자체를 고민 중이라면 도움은 상대적으로 적습니다.

일반 프롬프트와 turborepo-caching는 무엇이 다른가요

일반 프롬프트는 모노레포 전반에 대한 두루뭉술한 조언을 줄 가능성이 큽니다. 반면 turborepo-caching 스킬은 범위가 더 좁습니다. Turborepo pipeline 설정과 실서비스 환경의 캐싱 패턴에 초점을 맞춥니다. 이런 좁고 선명한 범위 덕분에 보통 turbo.json 추천 품질이 더 좋고, cache miss 디버깅도 더 정확해집니다.

어떤 경우에는 turborepo-caching를 쓰지 말아야 하나요

아래에 해당하면 이 스킬은 건너뛰는 편이 낫습니다.

• 저장소가 Turborepo를 사용하지 않을 때
• 캐시 설계보다 package manager 설정 지원이 더 필요할 때
• 주된 문제가 캐시가 아니라 빌드 정확성 자체일 때
• task 캐싱보다 프레임워크별 배포 가이드가 필요할 때

이 스킬은 설정 중심의 도구이지, 만능 성능 최적화기가 아닙니다.

이 스킬은 remote caching도 다루나요

네. 의사결정 수준에서는 다룹니다. 원본 자료에서도 remote caching과 CI/CD 최적화를 명시적인 사용 사례로 포함합니다. 다만 사용하는 CI 플랫폼, secret 관리 제약, 개발자 간에 캐시 아티팩트를 머신 간 공유할지 여부는 직접 제공해야 합니다.

turborepo-caching로 cache miss 디버깅도 가능한가요

가능합니다. 오히려 가장 실용적인 활용처 중 하나입니다. 아래 항목을 검토하는 데 도움이 됩니다.

• 빠졌거나 지나치게 넓은 outputs
• 숨겨진 파일 의존성 또는 env 의존성
• 잘못 나뉜 task 경계
• 일반 빌드처럼 모델링된 비캐시성 task 또는 persistent task

디버깅할 때는 “이건 캐시 hit가 나야 하는데 안 났다” 같은 실제 사례를 함께 주는 것이 좋습니다.

turborepo-caching는 대규모 모노레포에서만 의미가 있나요

아니요. 작은 모노레포에서도 빌드가 자주 돌거나 CI 비용이 크다면 충분히 이점이 있습니다. 패키지, 앱, pipeline 수가 늘어날수록 가치가 더 커지는 것은 맞지만, 웹 앱 하나와 공유 패키지 몇 개 정도의 비교적 작은 저장소에도 여전히 유용합니다.

turborepo-caching 스킬을 더 잘 활용하는 방법

실제 task graph를 에이전트에 제공하세요

turborepo-caching 결과를 가장 빠르게 개선하는 방법은 실제 스크립트와 패키지 관계를 주는 것입니다. 어떤 패키지가 어떤 패키지에 의존하는지, 어떤 task가 상위 빌드 산출물을 소비하는지도 포함하세요. 설명이 모호하면 안전하지 않을 수 있는 범용 캐시 템플릿으로 흘러가기 쉽습니다.

outputs를 구체적으로 명시하세요

약한 결과의 대부분은 output 디렉터리가 충분히 구체적이지 않아서 생깁니다. 각 task가 정확히 어디에 무엇을 쓰는지 알려주세요. 예를 들면 다음과 같습니다.

• apps/web build는 .next/에 기록
• packages/ui build는 dist/에 기록
• packages/config build는 lib/에 생성된 .js와 .d.ts 파일을 기록

이렇게 해야 에이전트가 추측이 아니라 실제로 쓸 수 있는 outputs 목록을 만들 수 있습니다.

환경 변수에 민감한 동작을 드러내세요

성능 최적화를 위한 turborepo-caching에서는 env 처리가 정확성이 깨지는 지점인 경우가 많습니다. 아래를 명시하세요.

• 빌드 시점 env vars
• CI 전용 vars
• public frontend vars
• 출력물에 영향을 주는 .env 파일

그리고 어떤 값은 cache key에 반영되어야 하고, 어떤 값은 반영되면 안 되는지 구분해 달라고 요청하세요.

비캐시성 task와 persistent task를 초기에 표시하세요

흔한 실패 패턴은 모든 것을 캐시하려는 것입니다. 아래에 해당하는 task가 무엇인지 먼저 알려주면 결과가 훨씬 좋아집니다.

• watch mode
• 로컬 개발 서버
• 오래 실행되는 백그라운드 프로세스
• 배포처럼 부작용이 있는 스크립트

이렇게 해야 에이전트가 persistent task를 일반적인 빌드 단계처럼 모델링하는 실수를 피할 수 있습니다.

설정 덤프만 말고, 근거까지 요청하세요

더 강한 turborepo-caching 가이드 워크플로는 주요 필드마다 설명을 요구하는 것입니다. 예를 들면:

Revise my turbo.json and explain why each task has cache, outputs, and dependsOn configured the way it is. Flag any assumptions you had to make.

이렇게 하면 설정을 적용하기 전에 실수를 더 쉽게 발견할 수 있습니다.

실행 후 2차 검증을 꼭 하세요

첫 번째 결과를 받은 뒤에는 실제로 task를 돌려 보고 관찰된 동작을 다시 전달하세요.

• 어떤 명령이 cache hit 되었는지
• 어떤 명령이 예상과 다르게 miss 되었는지
• 복원된 아티팩트가 올바른지
• CI와 로컬 결과가 다른지

보통 이 두 번째 반복에서 스킬의 가치가 가장 커집니다. 실제 miss 사례가 드러나야 초안 단계에서 추론할 수 없었던 숨은 입력값이 보이기 때문입니다.

안전한 정밀도와 넓은 캐싱을 비교해 달라고 하세요

turborepo-caching 활용을 다듬을 때는 에이전트에게 아래 두 옵션을 비교해 달라고 요청하세요.

• 정밀한 무효화를 우선하는 보수적 설정
• 최대한 캐시 재사용을 노리는 공격적 설정

이 접근은 “최고의 설정”을 달라고 하는 것보다 더 나은 의사결정 틀입니다. 정답은 오래된 아티팩트를 감수할 수 있는 정도와 연산 비용 사이의 균형에 달려 있기 때문입니다.

프롬프트를 측정 가능한 목표에 묶어두세요

좋은 개선 프롬프트는 아래처럼 구체적인 목표를 담고 있습니다.

• CI 빌드 시간을 40% 줄이기
• docs만 바뀌었을 때 apps/web를 다시 빌드하지 않기
• 개발자 간 빌드 캐시 공유하기
• 변경 없는 패키지의 반복 테스트 실행 없애기

측정 가능한 목표가 있어야 에이전트가 단순한 pipeline 설계와 더 세분화된 설계 사이에서 올바르게 선택할 수 있습니다.