한 줄 요약: Claude Code 자동화 플러그인 AIDD.Architecture-Patterns 에 지금까지 구현한 것(Slack·GitHub·Apidog/Postman/Swagger 연동, Clean+Hexagonal·MVC, GitHub Actions·ArgoCD)과 앞으로 붙일 계획(봇·기획 연동·모니터링)을 한자리에 정리했습니다 — 연동도 아키텍처도 배포도 결국 "하나의 일관된 문서 규칙과 포트" 위에서 굴러야 한다는 이야기입니다.
요즘 Claude Code 자동화 플러그인을 하나 만들고 있다. 이름은 AIDD.Architecture-Patterns. 한 줄로 말하면 “아키텍처 패턴과 외부 연동, 배포 자동화를 ‘하나의 문서’에서 일관된 규칙으로 굴리자”는 시도다. 이 글은 내가 직접 구현한 자동화 기능과 스타일, 그리고 앞으로 붙일 플러그인·템플릿·모니터링 계획을 세분화해 정리한 기록이다.
1. 왜 만들었나 — “하나의 문서”라는 지향점
프로젝트를 새로 시작할 때마다 같은 일을 반복한다. 폴더 구조를 잡고, 포트(interface) 경계를 긋고, CI/CD를 깔고, API 스펙을 Apidog·Postman에 올리고, Slack 알림을 붙이고, ArgoCD에 등록한다. 매번 손으로 하면 사람마다·프로젝트마다 미묘하게 달라진다.
그래서 목표를 이렇게 잡았다. “하나의 일관된 문서/템플릿 규칙으로, 연동(Slack·GitHub·Apidog·Postman·Swagger·Obsidian)과 아키텍처 스타일(Clean+Hexagonal·MVC), 그리고 배포 자동화(GitHub Actions·ArgoCD)를 모두 구동한다.” 모든 패턴은 Clean Architecture + Hexagonal(Port-driven) 을 기본값으로 삼고, 같은 14-섹션 틀을 따른다. 그래서 언어가 달라도 패턴끼리 1:1로 비교가 된다.
2. 내가 만든 자동화 플러그인의 정체
이것은 단순한 ‘코드 스니펫 모음’이 아니라 Claude Code 플러그인 마켓플레이스 다. 즉, Claude Code에 설치하면 슬래시 커맨드(slash command) 와 스킬(skill) 이 생기고, 자연어 한 줄로 자동화가 돌아간다. 동작 골격은 이렇다.
사용자의 자연어 / 슬래시 커맨드
│ 예) /infra-init --with ci,delivery
▼
Skill (SKILL.md) ── 의도 해석 · 인자 파싱
│
▼
Script (bash / python / mjs) ── 실제 파일 생성 · 외부 API 호출
│
▼
결과물 (워크플로 파일 · 매니페스트 · API 스펙 · Slack 채널 …)
각 플러그인은 category 라는 분류축으로 묶여 있고, 모든 아키텍처 패턴은 동일한 14-섹션 한국어 템플릿을 따른다: ①패턴명 ②목적 ③적용 대상 ④문제 상황 ⑤구조 ⑥책임 분리 ⑦폴더 구조 예시 ⑧코드 예시 ⑨장점 ⑩단점 ⑪언제 쓰지 말아야 하는지 ⑫MSA에서의 역할 ⑬Clean/Hexagonal 관점에서의 위치 ⑭확장 포인트.
| category | 플러그인 | 한 줄 설명 |
|---|---|---|
| language | arch-patterns-language | Go·Java·Node·React·Flutter — 언어별 Clean+Hexagonal 패턴 |
| infra | arch-patterns-infra | 10개 concern(platform·persistence·messaging·identity·workflow·observability·ci·delivery·migration·secrets) + 위상정렬 초기화 |
| bridge | arch-patterns-slack / -github / -figma | Slack·GitHub·Figma 연동 브리지 |
| workflow | arch-patterns-mvp / -demo | MVP 부트스트랩 / 시연 영상 자동 녹화 |
| notation | arch-patterns-flow / -diagrams | 처리과정·다이어그램을 ‘버전 관리되는 계약(contract)’으로 |
3. 지금까지 구현한 자동화
3-1. 외부 연동 (Integration)
- Slack — “as Code” 두 갈래. App-Manifest-as-Code(앱의 표시·스코프·슬래시 커맨드·이벤트·소켓모드를 YAML/JSON 매니페스트로 선언 → 검증·적용)와 Channel-Taxonomy-as-Code(채널 접두어 분류 체계를 SoT로 두고 멱등하게 생성·분류). 지금은 ‘초기화(Init)’와 ‘동기화(Sync)’까지 구현돼 있다.
- GitHub — GitHub Projects/Issues 를 source-of-truth 로 두고 단방향 전파. Project Write-Through(로컬 입력 → GitHub push, REST+GraphQL 이중 API, state-code 기반 멱등 워커)와 Webhook Fanout(webhook 수신 → 정규화 → 다중 도착지 fan-out).
- Apidog · Postman · Swagger(OpenAPI) — API 스펙을 단일 진실 공급원(spec-as-SoT) 으로 두는 파이프라인.
apidog-init/postman-init스킬이 하나의environments.yaml에서 dev/staging/prod 환경을 통일하고, OpenAPI 스펙을 다중 싱크(Apidog·Postman)로 내보낸다. (Apidog의 ‘import가 환경을 리셋하는 버그’도 server-info strip 으로 회피.) 이쪽도 현재는 Init + Sync 범위다.
3-2. 아키텍처 스타일
- Clean Architecture + Hexagonal (기본값) — Handler →(inbound port)→ UseCase →(outbound port)→ Repository/Adapter. “UseCase 는 프레임워크·HTTP·DB 드라이버를 절대 import 하지 않는다”가 비협상 규칙이다.
- MVC — 빠른 반복이 필요한 구간을 위한 보완 스타일(예: Spring MVC 빠른 이터레이션 패턴). 포트 없는 순수 MVC는 reference-only로 명시해 베이스라인과 구분한다.
- 언어별 매핑 표 — 같은 ‘Handler/UseCase/Port/Repository’ 개념을 Go·Java·Node·React·Flutter 각각의 관용구로 1:1 대응시켜 놓았다.
3-3. 배포 자동화 (GitOps)
- GitHub Actions —
github-actions-init스킬이 서비스 리포에 9-파일 워크플로 셋을 떨군다. PR 머지 기반 build/deploy, ChatOps/deploy, 재사용 가능한workflow_call빌드/프로모트/매니페스트/배포 잡, 옵셔널 Slack 알림까지. - ArgoCD —
argocd-init스킬이 로컬(kind) 또는 클러스터에 ArgoCD를 설치하고 dev/staging/prod 프로젝트를 만든다. App-of-Apps 와 ApplicationSet 으로 서비스 자동 등록까지 구성. - 위상정렬 초기화 —
/infra-init --with <concern1,concern2,…>가 concern 간depends_on의존성을 위상정렬해서 필요한 것만 순서대로 깔아준다.
3-4. 워크플로 / 표기법 자동화
- MVP 부트스트랩 — 레퍼런스 백엔드·프론트엔드를 클론하고 규칙에 맞는 타깃 리포를 만든 뒤, “도커로 구현해줘 / 시연 영상 만들어줘” 같은 짧은 자연어로 Docker 환경과 시연 녹화 하네스를 합성.
- 시연 영상 자동 녹화 — 시나리오(YAML)를 입력으로 웹(Playwright/CDP → WebM/MP4)·모바일 푸시까지 녹화.
- 표기법(notation) — 코드 ↔ 한국어 ‘처리과정’ 상호 변환, 그리고 Mermaid/PlantUML/C4/BPMN 다이어그램을 ‘코드 옆에 사는 포트 계약’으로 취급.
4. 자동화 “스타일(템플릿)” 그 자체
이 플러그인의 핵심은 개별 기능이 아니라 ‘틀(template)을 강제하는 방식’ 이다.
- 14-섹션 PATTERN 템플릿 — 모든 패턴이 같은 프론트매터(id·language·layer·style·msa_role·maturity·tags)와 14개 섹션을 갖는다. 1~3번 규칙을 못 지키면
draft로 간주되어 main에 머지될 수 없다. - concern manifest — infra의 각 concern은
depends_on+provides{patterns,skills,commands}+env계약을 manifest.yaml 로 선언한다. 그래서 “무엇을 깔면 무엇이 따라온다”가 문서로 고정된다. - 프로파일 분리 규약 — 공개용 일반(generic) 자산과 조직-특화 자산을 경로 규칙으로 분리하고, pre-commit 훅이 이를 강제한다. (외부 사용자는 placeholder 치환만으로 그대로 돌릴 수 있다.)
5. 최종 지향점 — 하나의 문서로
정리하면 목표는 이렇게 한 그림으로 수렴한다.
┌──────────────────────────────────────────┐
│ 하나의 문서 / 템플릿 규칙 │
│ (14-섹션 PATTERN + concern manifest) │
└───────────────┬──────────────────────────┘
│
┌──────────────┬─────────────┼──────────────┬───────────────┐
▼ ▼ ▼ ▼ ▼
연동 아키텍처 배포 자동화 워크플로 표기법
Slack/GitHub Clean+Hex / GitHub Actions MVP / Demo Flow /
Apidog/Postman MVC → ArgoCD GitOps 부트스트랩 Diagrams
/Swagger
“연동 + 아키텍처 + 자동화”를 각각 손으로 세팅하던 것을, 같은 규칙을 따르는 하나의 문서 체계가 구동하게 만드는 것 — 그게 이 플러그인이 가려는 방향이다.
6. 앞으로 구현할 플러그인 (세분화 계획)
지금까지는 연동의 ‘초기화(Init)’와 ‘동기화(Sync)’ 에 집중했다. 다음 단계의 핵심은 “세팅을 코드로 굳히고, 사람의 반복 응대를 봇으로 옮기고, 기획·PM 단계까지 포트로 끌어오는 것” 이다. 영역별로 쪼개 보면 이렇다.
6-1. Slack — Init/Sync 에서 ‘봇·설정’ 으로 확장
| 구분 | 내용 | 상태 |
|---|---|---|
| 현재 | App-Manifest Init + Channel-Taxonomy Sync (앱/채널을 코드로 선언·생성) | 구현됨 |
| 계획 ① | CS 응대 봇 — 문의를 받아 1차 응대 → 분류 → 담당 채널/이슈로 라우팅 | 계획 |
| 계획 ② | 기능 수정 요청 봇 — 슬랙에서 받은 수정 요청을 구조화 → GitHub Issue/Project 로 자동 등록 | 계획 |
| 계획 ③ | 알림 설정(notification settings) — 채널별·이벤트별 알림 정책을 코드(SoT)로 선언·적용 | 계획 |
| 계획 ④ | 채널 설정(channel settings) — 토픽/목적/권한/북마크/canvas 까지 자동 구성 범위 확대 | 계획 |
6-2. Apidog / Postman / Swagger — ‘스펙 동기화’ 에서 ‘기획 연동’ 으로
| 구분 | 내용 | 상태 |
|---|---|---|
| 현재 | Init + Sync (OpenAPI 스펙 → Apidog/Postman 다중 싱크) | 구현됨 |
| 계획 ① | PM·기획팀 프로젝트 설정 연동 — 기획 산출물 ↔ API 스펙 ↔ 도구 프로젝트를 한 흐름으로 연결 | 계획 |
| 계획 ② | Swagger Template Style — 스펙 작성 자체를 위한 표준 템플릿 스타일 | 계획 |
6-3. PM·기획 연동 — Port 부터 새로 설계
위 봇·기획 연동을 깔끔하게 묶으려면, 외부 도구(Slack·GitHub·기획 도구)를 직접 호출하는 대신 포트(outbound port) 로 추상화해야 한다. 그래야 도착지가 바뀌어도 UseCase 는 그대로다. 새로 정의할 포트의 밑그림은 이렇다.
ProjectSettingsPort— PM/기획팀의 프로젝트 설정(보드·라벨·마일스톤 등)을 읽고/반영PlanningSourcePort— 기획 산출물을 API 스펙·이슈의 입력으로 끌어오는 인바운드 소스BotCommandPort— 봇이 받은 명령(문의·수정요청)을 도메인 UseCase 로 넘기는 1차 어댑터 경계NotificationPolicyPort— 알림 정책(누구에게·어떤 채널로·언제)을 코드로 다루는 경계
핵심은 ‘봇·기획 도구·알림’을 기능별로 따로 붙이지 않고, 같은 포트 규약 위에 올리는 것이다.
6-4. 모니터링 — 처음부터 시작 (from scratch)
이 영역은 아직 observability concern 의 매니페스트(틀)만 잡혀 있고 패턴은 0개다. 즉 완전히 처음부터 설계한다.
- 수집/시각화 스택: Prometheus(메트릭) + Grafana(대시보드) + Tempo(분산 트레이싱), OpenTelemetry collector 로 trace 전파 포트를 표준화.
- Naver 스타일 APM — 콜 트리/트랜잭션 추적 중심의 ‘한 화면 진단형’ 구성을 목표로.
- Datadog 스타일 APM — 서비스 맵 + RED/USE 지표 + 트레이스-로그-메트릭 상관(correlation) 중심 구성을 목표로.
- 연동 지점: 위 6-3 의 포트들과 같은 결로,
TracePropagationPort·MetricSinkPort를 정의해 서비스 코드와 모니터링 백엔드를 분리.
6-5. Obsidian Template Style
Obsidian 볼트/노트 구조를 표준화하는 템플릿 스타일. 지금은 일부 문서에 노트 브리지 아이디어만 있고 전용 패턴은 아직 없다. 위 ‘하나의 문서’ 지향과 맞물려, 지식/설계 문서를 같은 규칙으로 관리하는 마지막 퍼즐로 둔다.
7. 마무리
지금까지는 ‘초기화·동기화’ 까지 왔다. 다음 단계는 봇·설정·기획 연동·모니터링 이고, 그중 모니터링은 백지에서 시작한다. 채워야 할 칸이 많지만 방향은 분명하다 — 연동도, 아키텍처도, 배포도, 봇도, 모니터링도, 결국 ‘하나의 일관된 문서 규칙과 포트’ 위에서 자동화한다. 진행되는 대로 이 글에 이어서 기록을 남길 생각이다.
이어서 읽기
‘규칙 하나로 굴린다’는 생각은 코드에서 먼저 해 봤고, 이 플러그인은 그 발상을 작업 흐름 쪽으로 옮긴 것이다. 뿌리가 된 두 글을 아래에 둔다.
답글 남기기