매뉴얼을 작성할 바에는 그대로 Claude의 스킬로 만들어버리자

문서 작성 시 흔히 발생하는 일들

• 반년 전에 작성된 이후 실태와 미묘하게 어긋나 있어 유지보수가 되지 않음

• "이 부분은 ○○님께 여쭤보세요"라고 되어 있어 결국 특정 개인에게 의존하게 됨 (속인화)

• 절차대로 했을 텐데 도중에 막힘

• 마지막에 가서야 끝에 추가되어 있던 트러블슈팅 (Troubleshooting) 장의 존재를 깨달음

• 새로운 멤버가 올 때마다 옆에서 붙어서 설명해야 함

• 매뉴얼과 작업 화면을 왔다 갔다 하느라 시선 이동만으로도 피로함

• 애초에 쓰는 것이 귀찮아서 뒤로 미룸

특히 릴리스 (Release) 작업이나 테스트 환경 구축과 같이 "정기적이지만 절차가 많은 작업"은 매뉴얼만으로는 아무래도 한계가 있습니다.

매뉴얼은 어디까지나 "읽기물"이기 때문에, 문서와 작업 화면을 번갈아 가며 보면서 "음, 다음은..." 하고 실제 자신의 조작 화면과 매뉴얼을 대조하는 것이 꽤 힘듭니다.

특히 외부에서 MacBook의 단일 화면으로만 작업 공간이 있을 때는 윈도우 전환의 번거로움 때문에 특히 스트레스가 심했습니다.

그런데 최근 Claude가 등장하여 코딩 등으로 큰 도움을 받고 있는 와중에 문득 생각이 떠올랐습니다.

매뉴얼도 Cowork의 스킬로 만들면 엄청 편하지 않을까???

그래서 실제로 두 가지 업무에서 시도해 보았기에, 그 체험을 공유합니다.

Cowork의 스킬이란 아주 간단히 말하면 **"Claude에게 전달할 수 있는 매뉴얼"**입니다.

일반적인 매뉴얼 (Markdown으로 작성된 문서 등)과의 차이점은 다음과 같습니다.

매뉴얼	Cowork의 스킬
읽는 사람	인간이 읽음
...

매뉴얼을 별도 탭으로 열어 왔다 갔다 할 필요 없이, Cowork의 채팅상에서 대화하며 진행할 수 있으므로 시선 이동의 스트레스도 없어질 것 같습니다.

게다가 Claude로 실행 가능한 부분은 직접 해주게 되므로 일석이조입니다.

저희 MGRe의 Android 앱은 릴리스를 할 때마다 다음과 같은 8가지 절차를 수행해야 합니다.

• 릴리스 브랜치 (Release Branch) 생성
• 버전 번호 업데이트 (복수 파일)
• 커밋(Commit) & 푸시(Push)
• PR의 description 작성
• aar 라이브러리 생성 및 배포
• 템플릿용 브랜치 생성 및 업데이트
• 릴리스 노트 (Release Note) 업데이트
• 사내 각 부서에 릴리스 공지

매뉴얼은 있지만, 업데이트할 파일의 위치나 커맨드 (Command) 인수를 매번 확인해야 해서 1회 릴리스에 약 반나절이 걸리기도 했습니다.

특히 까다로운 것이 "PR의 description 작성"으로, PR 번호나 Backlog의 티켓 정보를 수작업으로 찾아 분류하고 정형화하는 작업이 은근히 힘들었습니다.

Cowork로 함께 릴리스 작업을 하면서 그 절차를 그대로 스킬로 만들었습니다.

나중에 스킬화할 수도 있지만, Cowork에서 초반에 "지금부터 수행할 작업을 스킬화하고 싶다"라고 말하고 매뉴얼을 첨부하면 원활하게 이행할 수 있습니다.

다음부터는 스킬이 있는 상태에서 "릴리스 작업을 하고 싶다"라고 Cowork에 전달하는 것만으로, Claude가 대화 형식으로 진행해 줍니다.

• "다음 버전은 무엇으로 할까요?"라고 선택지를 주며 물어봐 줌
• build.gradle이나 README.md의 버전 번호를 자동으로 수정해 줌
• git log에서 PR 목록을 가져와서 PR의 description을 자동 생성해 줌
• Slack 공지 문구도 내부 변경 사항을 제외하고 작성해 줌
• git 조작이나 빌드 등 로컬에서만 할 수 있는 작업은 복사/붙여넣기용 커맨드를 생성해 줌
• 에러가 발생하면 원인을 분석하여 복구 절차를 제시해 줌

정말 간단합니다~

매뉴얼과 대조하며 하는 수작업 → Cowork와의 대화 기반 반자동 작업으로 바뀐 덕분에, 작업 시간과 심리적 부담이 대폭 줄었습니다.

작업 시간도 대략 1시간 정도로 완료할 수 있게 되어 대폭 절감되었습니다. 해냈다!

QA 테스트용 빌드에서는 테스트 패턴 스프레드시트 (Spreadsheet)를 기반으로 설정 파일을 수정하는 작업이 있습니다. 앱의 회원 방식이나 계약 플랜을 비롯한 설정 항목이 많아, 패턴마다 브랜치를 따서 설정 파일을 교체하는 작업은 정확성이 요구되는 데 비해 그저 단조로웠습니다.

이것도 스킬화했습니다. Cowork 채팅에 스프레드시트를 첨부하고 "QA 테스트 설정을 부탁합니다"라고 말하면, Claude가 패턴을 분석하여 필요한 설정 변경을 모두 실행해 줍니다.

도중에 다른 멤버가 작업에 합류하는 케이스에도 대응하고 있어, "베이스 브랜치는 이미 만들어 두었나요?"라고 묻도록 설정했기에 환경 구축의 중복도 방지하고 있습니다.

매뉴얼과 달리 할 수 있는 부분은 자동으로 처리해 주기 때문에 그 시점에서 매우 편리하긴 하지만,

개인적으로 가장 큰 장점은 **「작업의 재현성(Reproducibility)이 높다」**는 점이라고 느꼈습니다.

매뉴얼(手順書)은 올바른 절차가 적혀 있더라도 실행하는 것은 모두 인간입니다.

도중에 에러가 발생하면 스스로 조사해서 대처할 수밖에 없으며, 매뉴얼에 적혀 있지 않은 이례적인 상황(Irregular)에는 대응할 수 없습니다.

매뉴얼과 작업 화면 사이를 시선이 계속 왔다 갔다 해야 합니다.

또한 휴먼 에러(Human Error)가 개입될 확률도 매우 높습니다.

Cowork의 스킬이라면 동일한 화면의 채팅창에서 "다음에 이것을 합시다"라고 안내해 주기 때문에 매뉴얼을 잘못 읽는 일은 거의 없을 것입니다.

파일 편집처럼 자동으로 할 수 있는 부분은 실행하고, 인간만이 할 수 있는 부분은 복사/붙여넣기용 명령어를 준비해 줍니다. 에러가 발생하면 "이것이 원인이라고 생각합니다. 이렇게 하면 고칠 수 있습니다"라고 제안도 해주었습니다 (과신은 금물).

만든 스킬을 팀에 전개하는 것도 Cowork 상에서 완결됩니다.

채팅 화면 왼쪽 상단 부근의 제목 부분에서 작업을 스킬로 만들 수 있습니다.

다만 처음부터 정형화된 작업을 스킬화하려고 생각하는 경우에는,

채팅으로 작업을 시작하기 전에 "지금부터 수행할 작업을 최종적으로 스킬로 만들고 싶다"라고 전달해 두면, 상대측에서 처음부터 그럴 의도로 준비해 주기 때문에 훨씬 매끄럽게 진행되는 느낌입니다.

그 후에 매뉴얼로서 준비된 것이 있다면 해당 마크다운(Markdown) 등을 전달하면 그 내용에 따라 함께 작업을 수행해 줍니다.

1. Cowork의 채팅 화면 왼쪽 하단에 있는 + 아이콘에서 **「스킬 관리」**를 연다.

2. 스킬 목록에서 공유하고 싶은 스킬을 찾아 오른쪽 상단의 「공유」 버튼을 클릭한다.

3. 공유 다이얼로그에서 "일반 액세스"를 **「조직의 모든 구성원」**으로 설정하고 「공유」를 클릭한다.

이렇게 하면 조직의 모든 멤버가 이 스킬을 사용할 수 있게 됩니다.

사용하는 측은 「스킬 관리」를 열고, 왼쪽 상단 + 아이콘에서 **「스킬 열람」**을 통해 디렉토리를 엽니다.

여기서 **「공유됨 탭」**을 선택하면 사내의 다른 사람이 만들어 공개한 스킬이 표시되므로, 여기서 추가하면 OK입니다.

이렇게 하면 자신의 스킬 목록에 추가되므로, 이후에는 Cowork에서 "릴리스 작업을 하고 싶다" 또는 "QA 테스트 설정을 부탁합니다"와 같이 지시하면 채팅을 통해 작업을 시작할 수 있습니다.

그렇다고는 해도 스킬이 만능은 아니기에, 한계점도 솔직하게 적어 두겠습니다.

로컬 조작은 인간의 몫: git의 push나 Gradle 빌드 등, 로컬 환경에서만 실행할 수 있는 조작은 Claude가 할 수 없습니다. 명령어는 생성해 주므로 Cowork 화면에서 복사/붙여넣기하여 실행하는 형태가 됩니다. 이 부분은 현재로서는 어쩔 수 없습니다.

스킬 자체의 유지보수(Maintenance)가 필요함: 프로젝트 구성이 바뀌면 스킬도 업데이트해야 합니다. 다만 매뉴얼 업데이트와 달리, Cowork에서 "스킬의 이 부분을 수정해 줘"라고 요청하면 해주기 때문에 허들은 상당히 낮다고 생각합니다.

초기에는 공수가 들어감: 스킬을 만들려면 우선 작업의 전체상을 정리해야 합니다. 앞서 언급했듯이 Cowork에서 함께 작업하며 스킬로 완성해 나가면, 실질적인 추가 비용은 거의 없습니다.

스킬화에 적합하지 않은 작업도 있음: 단 한 번뿐인 작업이나 매번 방식이 완전히 다른 작업(신기능 설계 등), 의도적으로 사람에게 익히게 하려는 교육적인 작업 등은 스킬화해도 이점이 적습니다. "절차에 패턴이 있고 반복되는 작업"이 스킬화에 적합합니다.

과신은 금물: 스킬이 있더라도 Claude의 제안이 항상 옳다는 보장은 없습니다. 특히 에러 대응이나 복구(Recovery) 제안은 그대로 믿지 말고, 스스로 반드시 최종 확인을 하는 습관을 들여 놓는 것이 좋습니다. 정말로요.

"매뉴얼을 작성하는 것" 자체가 결코 나쁜 일은 아닙니다.

하지만 그 매뉴얼이 "정기적으로 실행하는 작업", "절차가 많아 실수하기 쉬운 작업", "인수인계가 힘든 작업"에 관한 것이라면, Cowork의 스킬로 만들어 버리는 편이 압도적으로 편하다고 느낍니다.

환경 구축 절차, 정기적인 데이터 집계, 코드 리뷰 체크리스트, 장애 대응 런북(Runbook) 등등, "매뉴얼을 작성해 볼까?"라는 생각이 들 때 "이거, Cowork 스킬로 만들 수 없을까?"라고 생각하며 시도해 보는 것도 좋을 것 같습니다.