프롬프트를 코드처럼 다루기: 콘텐츠 엔지니어의 AI 워크플로우

Source: Pulumi Blog

위에 제공된 링크에 포함된 전체 텍스트를 알려주시면, 해당 내용을 한국어로 번역해 드리겠습니다. 현재는 번역할 본문이 제공되지 않았습니다. 텍스트를 복사해서 보내주시면 바로 번역해 드리겠습니다.

AI가 해결하는 진짜 문제

모두가 AI가 당신을 더 빠르게 만든다고 이야기합니다. 그것도 틀리지 않지만, 가장 흥미로운 부분은 아닙니다 — 적어도 저에게는요.

가장 흥미로운 부분은 시작 문제에 AI가 미치는 영향입니다. 저는 ADHD 뇌를 가지고 있습니다(공식 진단은 아니지만, 스스로 인식할 정도로 상황을 알고 있습니다). 이것이 대부분의 작업과의 관계에 어떤 의미가 있는지 압니다: 문제를 보고, 이해하고, 해결하고 싶어하지만, 시작이라는 무게가 나를 완전히 짓눌러 버립니다.

작업에 막혔을 때, 문제는 거의 절대 “뭘 해야 할지 모른다”는 것이 아닙니다. 내 뇌가 완성된 결과물을 작업 기억에 모두 담아두면서 동시에 첫 번째 단계를 만들어내려 하기 때문입니다. 이는 엄청난 인지적 부담이며, ADHD 뇌에게는 종종 극복할 수 없습니다.

문제를 대화식으로 이야기하는 것은 전혀 다른 인지 부하를 제공합니다. 저는 Claude에게 이렇게 말할 수 있습니다:

“Here’s the issue, here’s what I’m trying to accomplish, here’s what’s weird about it.”

그 순간 저는 더 이상 빈 페이지를 바라보고 있지 않습니다. 대화 속에 있습니다. 발판이 존재합니다. 그 위에 무언가를 쌓아갈 수 있죠.

그 역동성은 저에게 새롭지 않았습니다. 이전에 Microsoft에서 교육 모듈을 작성하던 시절, 제가 최고의 결과를 낸 이유는 작업이 쉬워서가 아니라 협업자가 있었기 때문입니다—소리를 내며 생각을 정리할 친구, “자, 우리가 실제로 여기서 말하고 싶은 게 뭘까?”라고 물어볼 사람이 있었습니다. 그 대화형 발판이 회전과 출판 사이의 차이를 만들었습니다.

현재 제가 혼자 팀을 이끌고 있는 역할에서, AI는 바로 그 협업자가 되었습니다.

이 이야기는 생산성 이야기가 아닙니다.
인지적 보조 이야기에 가깝습니다. 그리고 진단을 받았든 받지 않았든 많은 사람들이 제가 설명하는 상황을 공감할 것이라고 확신합니다.

프롬프트를 코드처럼 다루기

대화형 스캐폴딩이 내 활성화 에너지를 낮출 수 있다면, 다음 질문은 명확했습니다: 필요한 사람이라면 누구에게든 이를 구축할 수 있을까?

AI를 사용해 이 문제를 해결하고 싶었지만, 일회성 프롬프트를 여러 개 작성하고 싶지는 않았습니다. 그렇게 하면 유지보수가 악몽이 되고, 나에게만 국한된 확장성을 가질 수 없었습니다. 시스템이 필요했습니다.

Claude Code는 이러한 재사용 가능한 프롬프트를 스킬이라고 부릅니다—다른 플랫폼에서도 플러그인이나 확장 같은 이름으로 같은 개념을 사용합니다.

첫 번째 실험: /docs-review

• 내 글을 일관된 기준 집합에 따라 검토하는 재사용 가능한 프롬프트.
• 특별한 기능은 없었습니다; 내 기분이나 커피 섭취량에 좌우되지 않는 신뢰할 수 있는 기준을 원했을 뿐이었습니다.

그때 생각이 떠올랐습니다: 우리 docs 레포의 모든 PR에 자동으로 적용되면 어떨까. 그래서 CI/CD 파이프라인에 연결했습니다.

메이건, 내 매니저는 이 기능을 아주 좋아했습니다 — 그리고 몇 주가 지나자 PR 품질이 눈에 띄게 향상된 것을 발견했습니다. 거의 모든 PR에서 기여자들이 자동 검토가 게시된 직후 “피드백 반영” 커밋을 스스로 푸시해, 내가 PR을 보기 전에 문제를 잡고 수정했습니다.

그때 무언가가 깨달았습니다: 이제 나는 프롬프트를 쓰는 것이 아니라 모듈을 쓰고 있었습니다 — 재사용 가능하고 조합 가능한 나만의 전문 지식 조각들.

컨텍스트 중앙화

이 통찰은 간단했지만 시스템 전체에 대한 사고 방식을 바꾸었습니다:

• 여러 스킬이 동일한 컨텍스트 — 우리 스타일 가이드, 검토 기준, 콘텐츠 표준 — 를 필요로 한다면, 그 컨텍스트는 한 곳에 존재하고 필요로 하는 모든 곳에서 사용되어야 합니다.
• 이를 소프트웨어 프로젝트의 공유 라이브러리에 비유할 수 있습니다.

나는 REVIEW-CRITERIA.md 파일을 단일 진실 소스로 만들어 Pulumi에서 “좋은” docs PR 검토가 어떤 모습인지 정의했습니다. 검토를 수행하는 모든 스킬은 이 파일을 참조합니다. 한 번만 변경하면 모든 것이 동시에 똑똑해집니다.

스타일 가이드, Hugo 규칙, 내비게이션 구조 역시 중앙 레퍼런스 파일에 보관해 어떤 스킬이든 끌어올 수 있게 했습니다.

왜 중요한가

• 토큰 효율성: 스킬마다 컨텍스트를 복제하면 토큰 사용량이 급격히 늘어납니다. 모듈화하면 이를 얇게 유지할 수 있습니다.
• 비용: CI/CD 파이프라인은 우아함보다는 비용을 더 신경 씁니다.

내가 계속해서 되새긴 정신 모델: Don’t Repeat Yourself (중복 금지). 이는 좋은 소프트웨어를 유지보수 가능하게 만드는 원칙과 동일합니다. AI 워크플로우에서도 유지보수성을 높여줍니다.

스킬 카탈로그

그때부터 시스템은 자연스럽게 성장했습니다. 한 번 이상 반복해서 수행하게 될 때마다 저는 스스로에게 물었습니다: “이걸 스킬로 만들 수 있을까?”

아래는 그 결과물 중 일부를 보여줍니다:

(새로운 필요가 생길 때마다 목록이 계속 추가됩니다.)

Takeaways

1. Package knowledge를 재사용 가능하고 버전‑관리되는 자산(스킬, markdown 레퍼런스 파일)으로 패키징합니다.
2. Automate를 가능한 모든 곳에서 자동화합니다—스킬을 CI/CD에 연결하여 대규모 일관성을 보장합니다.
3. Centralise 공유 컨텍스트를 중앙화하여 토큰 사용량을 낮추고 유지보수를 간단하게 합니다.
4. Treat AI prompts as code: 모듈식이며 테스트 가능하고 재사용 가능합니다.

즉석 프롬프트를 스킬 라이브러리로 전환함으로써, 나는 한 사람에게 의존하던 병목 현상을 지속 가능하고 확장 가능한 문서 워크플로우로 바꾸어 Pulumi의 누구든지 활용할 수 있게 만들었습니다.

누적된 기술 부채 해소

• /new-doc 및 /new‑blog‑post – 올바른 위치, 메타데이터, 내비게이션 연결을 통해 새로운 문서나 블로그 포스트를 추가하는 방법을 누구에게든 안내합니다. 엔지니어, 마케터, 누구든지. 기여 장벽이 크게 낮아졌습니다.
• /docs‑tools – 다른 레포 사용자들이 이 도구가 존재한다는 것을 발견하도록 돕습니다. 내부 도구의 발견 가능성은 실제 문제입니다.

Slack Integration

Slack의 내장 Claude 통합은 Claude Code 워크플로를 실행하는 Claude와 동일하지 않으며, 컨텍스트나 사용자 지정 지시사항을 공유하지 않습니다. 두 환경 모두에서 일관된 기준을 원한다면 자체 백엔드를 사용해야 합니다. 바로 그 역할을 /slack‑to‑issue 가 수행합니다.

Community Contributions

다른 사람들이 레포에 스킬을 기여하기 시작했습니다 — 제가 요청해서가 아니라, 패턴이 충분히 명확해서 확장할 수 있었기 때문입니다.

• 누군가 SEO 분석을 위한 스킬을 만들었습니다.
• 마케팅 팀이 자체 리뷰 기준을 추가했습니다.
• 엔지니어들이 제가 생각조차 못했던 워크플로우를 기여했습니다.

제가 개인적인 생존 도구로 만들었던 것이 공유 플랫폼이 되었습니다. 이는 프롬프트를 코드처럼 다뤘기 때문인데, 모듈화되고 재사용 가능하며 문서화되고, 기여에 열려 있었습니다.

정직한 제한 사항

• 인간 판단을 대체하는 것이 아니다. 이것들은 확률적 도구이며—대부분의 경우 옳지만 모든 경우는 아니다. /pr‑review는 PR을 자동으로 승인하지 않는다. 그것은 문제점을 강조하고 인간인 나에게 읽고 판단하도록 요청한다. AI가 첫 번째 검토를 하고, 나는 마지막 검토를 한다.
• 시스템도 아직 완성되지 않았다. 아마도 절대 완성되지 않을 것이다. 나는 아직도 검토 기준을 조정하고, 스킬이 이상한 결과를 내는 경계 사례를 찾으며, 새로운 문제점이 나타날 때마다 새로운 도구를 추가하고 있다. 프롬프트를 코드처럼 다루는 것은 소프트웨어처럼 다루는 것이다: 배포하고, 반복하고, 유지한다. 버전 1.0이 끝이라는 것은 없다.
• ADHD는 실제이지만 마법은 아니다. 여전히 마비가 이기는 날이 있다. AI는 시작에 필요한 활성화 에너지를 낮출 뿐, 완전히 없애지는 않는다. 여전히 내가 직접 나서야 한다. 그것도 자동화할 수 있겠지만, 그럼 전혀 다른 디스토피아가 될 것이다.

공유할 교훈

1. 모델과 비용을 파악하세요.

   • Pulumi에서는 주로 Claude를 사용하고, 저는 Claude Code에서 작업합니다; 대부분의 작업에서는 Opus보다 Sonnet을 사용합니다.
   • Opus는 훌륭하지만 비용이 훨씬 많이 들고, 잘 만든 Sonnet용 지시문으로도 대부분의 작업을 똑같이 효과적으로 처리할 수 있습니다.

2. 동료처럼 대하세요.

   • 명령만 내리고 결과를 기다리지 마세요. 모델에게 생각을 물어보고, 틀렸을 때는 반박하고, 당신의 추론을 설명하세요.
   • 대화형으로 많이 참여할수록 결과가 더 좋아집니다.
   • 정렬이 중요합니다: 복잡한 작업에 들어가기 전에 먼저 접근 방식을 논의하세요. 초기 몇 분의 정렬이 오해된 사양을 반복하는 것보다 낫습니다.

3. 필요할 때 개성을 추가하세요.

   • 저는 설정에 개인 지시를 추가했습니다 — 예를 들어 제가 캡틴 피카드인 척 할 때 함께 연기하거나, 상황에 맞게 화려한 언어를 사용하는 식입니다. (네, 실제 설정 값입니다.)
   • 겉보기에 가벼워 보일 수 있지만, 실제로 즐겨 쓰는 도구는 피하기보다 더 자주 사용하게 됩니다.

4. 워크플로를 모듈화하세요.

   • 모든 것을 하려는 거대한 단일 프롬프트를 작성하지 마세요.
   • 한 가지를 잘 수행하는 집중된 스킬로 나누고, 공통 컨텍스트는 중앙 레퍼런스 파일을 통해 공유하세요. 유지보수가 쉽고, 디버깅이 쉬우며, 실행 비용도 절감됩니다.

5. 프롬프트를 버전 관리하세요.

   • 스킬은 코드와 같습니다. 코드처럼 다루세요. 커밋하고, 리뷰하고, 반복 개선하세요.
   • 스킬을 수정한 뒤 이상한 출력이 나오면, 무엇이 바뀌었는지 확인하고 싶을 겁니다.

6. 토큰 소모율을 생각하세요.

   • CI/CD에서 자동화를 실행할 때 가장 중요합니다.
   • 스킬을 집중시켜 주세요 — 스타일을 검사하는 스킬은 Hugo 네비게이션 규칙을 로드할 필요가 없습니다. 모델은 제공된 내용만 읽으니 필요한 것만 전달하면 됩니다.

7. 모든 것이 프롬프트일 필요는 없습니다.

   • 스킬에는 스크립트를 포함할 수 있으며, 이는 종종 올바른 선택입니다.
   • 예시: 팀이 레포지토리에서 문서를 이동할 때는 히스토리를 보존하기 위해 git mv 로 이동해야 하고, 404를 방지하고 SEO를 보호하기 위해 프런트‑머터에 리다이렉트 별칭을 추가해야 합니다. 이는 이미 해결된 문제이므로 스크립트가 됩니다. 스킬은 해당 스크립트가 존재하고 무엇을 하는지만 알면 됩니다. Claude가 오케스트레이션하고, 스크립트가 실행합니다.

8. 모든 것이 생성형일 필요는 없습니다.

   • 결정적인 출력을 원한다면 확률적 도구를 사용하지 마세요.
   • 우리는 블로그 포스트용 메타 이미지를 생성하는 스킬을 가지고 있습니다 — 절차적으로, 생성형이 아니라. AI‑생성 이미지가 아니라, 스킬이 우리 시각 기준을 프로그래밍 방식으로 따르고 매번 일관된 결과를 만들어냅니다.

다음 단계

다음 단계는 이 도구 중 일부를 팀의 비기술적인 구성원, 특히 마케팅에게 제공하는 것입니다. 제가 구축한 기술은 터미널과 저장소에 대한 어느 정도의 편안함을 전제로 합니다. 엔지니어에게는 괜찮지만, 다른 사람들에게는 장벽이 됩니다. 친숙한 인터페이스가 그 장벽을 크게 낮출 수 있으며, 그것이 제가 현재 탐구하고 있는 방향입니다.

당신이 기술 작가이든, 개발자 옹호자이든, 혹은 AI가 워크플로에 어떻게 들어맞는지 고민하는 혼자 일하는 실무자이든, 여기서 설명한 접근 방식은 탄탄한 출발점이 됩니다.

• 도구도 중요하지만, 사고 모델이 더 중요합니다: 프롬프트를 코드처럼 다루세요.
• 재사용 가능하게 만드세요.
• 문서화하세요.
• 공유하세요.

우리의 문서 레포는 공개되어 있어, 필요한 사람이라면 누구든지 해당 기술을 활용할 수 있습니다. 비슷한 것을 만들고 있다면 자유롭게 참고하세요 — 혹은 기여해 주세요.

빈 페이지는 여전히 존재합니다. 하지만 좋은 협업자가 있으면 훨씬 덜 위협적으로 느껴집니다.