※ 이 기사의 일본어에는 약간 부자연스러운 부분이 있을 수 있습니다. AI의 언어 지원을 활용하며 작성되었습니다.

• 서론
• 1. Agent Skills란
• 2. SDLC로의 완벽한 매핑
• 3. 실제 프로젝트에서의 적용 방법 (나의 워크플로우)
• 4. 일반적인 프롬프트와의 차이점 – 3가지 「황금 차이점」
• 5. 요약
• 마지막으로

이 기사는 AI 코딩 툴 (Claude Code, Cursor, GitHub Copilot 등)을 일상적으로 사용하고 있는 엔지니어, 또는 앞으로 도입을 검토하고 있는 기술 리더를 대상으로 합니다.

저자에 대하여: 저는 현재 일본 시장을 대상으로 하는 시스템 개발을 담당하는 TOMOSIA VIETNAM에서 엔지니어로 일하고 있습니다. AI 코딩 툴을 매일 활용하는 가운데, "AI가 작성하는 코드의 품질이 안정적이지 않다"라는 과제에 직면했고, 그 해결책을 모색해 왔습니다.

이 기사의 목적:

• AI 코딩을 「프로토타입 작성 도구」에서 「프로덕션 품질의 코드를 작성하는 시니어 엔지니어」로 격상시키는 방법을 소개한다
• Google의 시니어 엔지니어 Addy Osmani가 공개한 리포지토리 agent-skills의 실천적인 사용법을 해설한다
• 실제 프로젝트에서 어떻게 적용하고 있는지를 구체적인 워크플로우와 함께 공유한다

상정 독자:

• AI 코딩 툴을 사용하고 있지만 「어딘가 부족하다」고 느끼는 분
• AI가 작성하는 코드의 품질을 높이고 싶은 엔지니어
• 팀에서 AI 활용 규칙을 정비하고 싶은 리더

우리는 AI가 몇 초 만에 코드를 작성할 수 있는 시대에 살고 있습니다.

하지만 현실적으로 AI가 생성하는 코드의 대부분은 「프로토타입으로는 충분한」 품질이며, 프로덕션 환경에 그대로 투입할 수 있는 수준에는 도달하지 못했습니다.

왜 그럴까요?

AI는 기본적으로 **최단 경로 (Shortest Path)**를 선택하기 때문입니다. 스펙 (Spec)을 건너뛰고, 테스트를 건너뛰고, 리뷰 프로세스를 건너뛰며 곧바로 코드를 쓰기 시작합니다.

이 문제에 대한 해결책이 바로 addyosmani/agent-skills 리포지토리입니다.

Google의 베테랑 엔지니어 Addy Osmani에 의해 구축된 이 리포지토리는 **24개의 구조화된 「스킬 (Skills)」**을 제공합니다. 이것들은 단순한 프롬프트가 아니라, 시니어 엔지니어의 워크플로우 그 자체를 패키지화한 것입니다. AI 코딩 에이전트 (Claude Code, Cursor, Gemini CLI 등)가 진짜 시니어 엔지니어처럼 생각하고 행동하도록 강제합니다.

이 리포지토리는 현재 63k Stars와 6.8k Forks를 획득하고 있으며, 그 주목도가 매우 높음을 알 수 있습니다.

특징:

• SKILL.md라는 순수 Markdown 파일로 설계되어 최신 AI 툴 대부분에 설치 가능

특히 주목해야 할 점은 SDLC 전체를 커버하는 7개의 슬래시 커맨드 (Slash Command)입니다:

이 7개의 커맨드가 표준 소프트웨어 개발 생명주기 (SDLC)의 6개 페이즈에 완벽하게 대응하고 있다는 점이 훌륭합니다.

AI에게 이것저것 지시하는 대신, 커맨드를 입력하는 것만으로 대응하는 스킬이 자동으로 기동됩니다.

다음은 이 스킬셋을 실제 프로젝트에서 어떻게 활용하고 있는지에 대한 예시입니다.

• 도구: /spec + 스킬 interview-me
• 사용법: 여러 페이지의 문서를 쓰는 대신, Claude Code를 열고 아이디어를 간단히 설명한 뒤 /spec이라고 입력합니다. AI는 즉시 interview-me

스킬을 실행하여, **비즈니스 분석가 (Business Analyst)**처럼 질문을 던지고, 제가 아직 인지하지 못한 **암묵적 요구사항 (Implicit Requirements)**을 끌어냅니다. - 결과적으로, 상세한 **PRD (제품 요구사항 정의서, Product Requirements Document)**가 생성됩니다.

• 수 페이지에 달하는 문서를 쓰는 대신, Claude Code를 열고 아이디어를 간단히 설명하고

• 도구 (Tool): /plan

• 사용법: - Spec이 완성되면 /plan이라고 입력합니다. - AI는 planning-and-task-breakdown 스킬을 실행하여, 작업을 **원자적 태스크 (Atomic Tasks)**로 분해하고, 난이도를 추정하며, 의존 관계를 정리합니다. - 이를 통해 **현실적인 공수 산정 (Effort Estimation)**이 가능해집니다.

• Spec이 완성되면

• 도구 (Tool): /build auto + 스킬 test-driven-development

• 사용법 (가장 시간을 절약할 수 있는 단계): - /build auto를 실행하면, AI는 Plan을 읽고 태스크를 순차적으로 구현합니다. - TDD (테스트 주도 개발, Test-Driven Development) 원칙에 따라, 먼저 테스트를 작성한 뒤 코드를 구현(Red-Green-Refactor)하며, 작은 단위로 커밋합니다. - UI 작업에서는 browser-testing-with-devtools 스킬을 활용하여, Chrome DevTools를 실제로 조작하며 DOM이나 네트워크를 검증합니다 (추측이 아닙니다).

• 도구 (Tool): /review & /code-simplify

• 사용법: - AI가 Pull Request를 완료하면, 사람이 500줄의 코드를 리뷰할 필요가 없습니다. - /review를 실행하면 code-review-and-quality 스킬과 code-reviewer.md 에이전트가 실행되어, 5가지 축 (설계, 기능, 복잡성, 테스트, 보안)을 기준으로 코드를 분석합니다. - 복잡한 코드에는 /code-simplify를 사용합니다. 이 스킬은 "Chesterton's Fence" (체스타턴의 울타리) 원칙을 적용하여, "왜 그곳에 코드가 존재하는가"를 이해하기 전까지는 삭제하지 않는 안전한 리팩터링을 실현합니다.

• 도구 (Tool): /ship

• 사용법: - 머지(Merge) 전에 /ship을 실행합니다. - 이 명령은 **맹목적인 배포 (Blind Deployment)**가 아니라, 다음과 같은 스킬 그룹을 실행합니다: - observability-and-instrumentation (로그 및 메트릭 확인) - ci-cd-and-automation (파이프라인 확인) - shipping-and-launch (Feature Flag, 롤백 계획 확인)

• AI는 체크리스트를 표시하며, 각 항목을 사람이 확인할 때까지 머지를 허용하지 않습니다.

• 머지 전에

이 스킬셋을 실제로 사용해 보면서, 일반적인 프롬프트와는 3가지 큰 차이점이 있다는 것을 발견했습니다.

1. 반론 (Counter-arguments): 각 스킬에는 AI가 자주 하는 변명(예: "테스트는 나중에 추가하겠습니다", "이 부분은 보안이 필요 없습니다")과 그에 대한 반론이 표 형식으로 기재되어 있습니다. 이를 통해 AI가 프로세스를 건너뛸 수 없게 만듭니다.

2. 종료 조건 (Exit Criteria): 모든 스킬에는 **종료 조건 (Exit Criteria)**이 정의되어 있습니다. "아마 괜찮을 것 같다"는 식으로는 불충분합니다. AI는 명확한 증거 (빌드 성공, 테스트 통과, 실제 로그 등)를 제시해야 합니다.

3. 토큰 효율성 (Token Efficiency): 각 스킬은 매우 상세하지만, AI는 처음에 짧은 설명만 읽습니다. 상세한 정보가 필요해진 시점에 비로소 외부 파일을 "열기" 때문에, 토큰 소비를 최소화할 수 있습니다.

만약 당신이 AI를 사용하여 코드를 작성하고 있는데 출력 품질이 불안정하다고 느낀다면, addyosmani/agent-skills를 꼭 시도해 보세요.

설치 방법:

• Claude Code의 경우: /plugin marketplace add addyosmani/agent-skills
• Cursor나 Windsurf의 경우: .md 파일을 규칙(rules) 디렉토리에 수동으로 복사

이 스킬셋을 도입한 이후, 저의 업무 방식은 크게 바뀌었습니다.

이전：AI의 「버그 수정 담당자」로서, 생성된 코드의 뒷처리를 하는 입장.

현재：「프로젝트 매니저 (Project Manager)」로서 전략적인 지시(/spec, /plan)를 내리고, AI에게는 전문적인 구현과 테스트에 집중하게 하는 입장.

결과적으로:

• ✅ 코드 품질 향상
• ✅ 기술 부채 (Tech Debt) 감소
• ✅ 납품 속도 대폭 향상

AI는 도구입니다. 하지만, **올바른 워크플로우 (Workflow)**를 부여함으로써 단순한 도구에서 신뢰할 수 있는 시니어 엔지니어로 변신시킬 수 있습니다.

여기까지 읽어주셔서 진심으로 감사합니다.

만약 **「시스템 개발을 의뢰하고 싶다」 「기술적인 상담을 하고 싶다」 「AI를 활용한 과제 해결 아이디어가 있다」**와 같은 고민이 있으시다면, 꼭 저희 TOMOSIA VIETNAM에 상담해 주세요.

• 💻 소프트웨어 수탁 개발 (Web · 앱 · 시스템)

• 🤖 AI 솔루션 (챗봇, 이미지 처리, LLM 응용)

• 📱 모바일 앱 개발 (iOS / Android)

• 🔌 Fintech / IoT 개발

• 🔧 브릿지 SE (BrSE) 지원 (일본어로 원활한 커뮤니케이션 가능)

• ISO/IEC 27001 (정보 보안) 인증 취득 완료 – 안심하고 맡기실 수 있습니다

• 일본어 대응 팀 – 일본의 문화와 비즈니스 관습을 이해한 멤버가 직접 대응

• 「Win-Win, Happy Together」 문화 – 장기적인 파트너십을 소중히 여깁니다

🔗 공식 사이트: tomosia.com