workspace

workspace skill 개요

workspace skill이 하는 일

workspace skill은 Claude Code가 모노레포나 여러 개의 repo 전반을 동적으로 파악하게 해 줍니다. 덕분에 각 폴더를 고립된 단위로 보지 않고, topology, shared types, API contracts, cross-project dependencies를 함께 고려해 추론할 수 있습니다. 프런트엔드, 백엔드, packages, shared services 전반에서 변경 사항의 일관성을 유지하고 drift를 줄여야 할 때, 특히 유용합니다.

누가 설치하면 좋은가

작업이 여러 codebase를 자주 넘나들거나, 하나의 repo 안에 contract와 dependency를 공유하는 여러 앱이 있다면 workspace를 설치하세요. workflow automation, platform engineering, 그리고 한 영역의 변경이 다른 영역에 어떤 영향을 주는지 Claude Code가 이해해야 하는 팀에 잘 맞습니다.

실무에서 중요한 이유

핵심 가치는 추상적인 “더 많은 컨텍스트”가 아닙니다. mismatch를 줄이는 데 있습니다. workspace guide는 Claude가 이미 존재하는 것, contract가 어디에 있는지, 무엇이 바뀌면 downstream code를 어디까지 업데이트해야 하는지를 추론하도록 돕습니다. 그래서 단순한 cross-repo 작업용 범용 프롬프트보다 실제 의사결정에 더 유용합니다.

workspace skill 사용 방법

설치하고 활성화하기

repo의 Claude skill install flow를 통해 skill을 사용한 뒤, Claude가 관련 repositories와 packages를 검사할 수 있는 workspace 안에서 작업하세요. workspace install 단계는 agent가 실제 project structure를 볼 수 있을 때만 의미가 있습니다. 따라서 Claude Code가 동작할 것으로 예상하는 동일한 environment에 설치해야 합니다.

올바른 입력으로 시작하기

좋은 workspace usage 프롬프트는 무엇이 바뀌는지, source of truth가 어디에 있는지, 무엇과의 호환성을 유지해야 하는지를 분명히 말합니다. 예를 들어, “services/payments의 checkout API를 업데이트한 뒤, apps/web와 packages/api-types의 shared types와 client calls도 확인해 줘”처럼요. 이런 식의 요청은 “버그를 고쳐줘”보다 훨씬 낫습니다. skill이 영향 범위를 정확히 매핑할 수 있기 때문입니다.

먼저 읽어야 할 파일

먼저 SKILL.md를 보고, 그다음 README.md, AGENTS.md, metadata.json을 확인하세요. 또한 존재한다면 workspace 전용 rules/, resources/, references/, scripts/ 폴더도 살펴보면 좋습니다. 이 repository에서는 보조 helper files가 없으므로 SKILL.md가 핵심 source입니다. 실제로 유용한 동작 대부분은 skill text 자체에서 나옵니다.

workflow와 함께 사용하기

실용적인 workspace for Workflow Automation 흐름은 이렇습니다. topology를 파악하고, shared contracts를 식별한 다음, 그것을 정의하는 files를 찾고, 이어서 dependent app 또는 repo를 업데이트한 뒤 breakage가 없는지 확인합니다. 가장 좋은 결과는 편집 전에 영향 범위를 추적해 달라고 요청할 때 나옵니다. 편집 후가 아니라요.

workspace skill FAQ

workspace는 monorepo에만 해당하나요?

아니요. workspace skill은 separate repo들이 하나의 system처럼 동작할 때도 도움이 됩니다. 특히 APIs, shared types, release timing이 서로 연결되어 있을 때 효과적입니다.

일반 프롬프트와 무엇이 다른가요?

일반 프롬프트도 변경을 요청할 수는 있습니다. 하지만 workspace skill은 일회성 프롬프트가 놓치기 쉬운 관계, 예를 들어 hidden dependencies나 contract ownership을 Claude가 점검하도록 돕습니다. 그래서 단일 파일처럼 고립된 작업보다 cross-repo edits에 더 적합합니다.

초보자도 쓰기 쉬운가요?

네, app boundaries와 변경 목표를 설명할 수 있다면 가능합니다. 깊은 repository 지식은 꼭 필요하지 않지만, 어떤 repo, package, service가 시작점인지 skill에 알려줘야 합니다.

언제는 사용하지 말아야 하나요?

cross-repo context가 중요하지 않은 작고 독립적인 수정에는 건너뛰는 편이 좋습니다. 한 file 또는 한 package 밖에서는 아무것도 깨지지 않는 작업이라면, workspace skill은 큰 이점 없이 오히려 overhead만 늘릴 수 있습니다.

workspace skill 개선 방법

source-of-truth 지도를 제공하세요

가장 강력한 입력은 각 contract의 담당 system을 명시합니다. 예를 들어, “OpenAPI schema는 services/api/openapi.yaml에 있고, generated client types는 packages/sdk에 있으며, UI calls는 apps/admin에서 발생합니다”처럼요. 이렇게 하면 workspace skill이 truth가 어디에 있어야 하는지 추측하지 않아도 됩니다.

호환성 제약을 먼저 밝히세요

변경이 behavior, versioned APIs, shared types를 유지해야 한다면 처음부터 분명히 말하세요. 무엇을 깨뜨리면 안 되는지, 무엇은 regenerate해도 되는지, 무엇을 수동으로 수정해야 하는지를 지정할수록 workspace skill의 성능이 좋아집니다.

편집 전에 영향 분석을 요청하세요

workspace skill 실행에서는 code changes 전에 간단한 dependency check를 요청하세요. 예를 들어, “영향을 받을 가능성이 있는 repos, packages, entry points를 나열한 뒤, 가장 안전한 edit order를 제안해 줘”처럼 말입니다. 이렇게 하면 Claude가 구현으로 곧장 뛰어들기보다 blast radius를 먼저 추론하게 되어 output quality가 높아집니다.

부분 결과에서 전체 결과로 반복하세요

첫 결과가 너무 넓다면 package, contract, repo boundary 기준으로 범위를 좁혀서 skill을 다시 실행하세요. 가장 좋은 workspace guide workflow는 한 번은 system을 매핑하고, 두 번째는 발견한 context를 바탕으로 범위를 좁힌 변경을 실행하는 방식입니다.