| name | sync-architecture |
| description | Use this skill when the user says "sync architecture", "update architecture", "아키텍처 동기화", "아키텍처 업데이트", "구조 정리", "ARCHITECTURE.md 만들어줘", or wants to generate/refresh a structural overview of the project for AI agents. Starts with ARCHITECTURE.md and splits into ARCHITECTURE-{AREA}.md files when the project grows large enough to warrant separation.
|
Sync Architecture
Invocation
/sync-architecture
인수가 없어도 된다. 실행할 때마다 현재 프로젝트를 분석해 아키텍처 파일을 생성·갱신·분리·통합한다.
파일 구조:
- 기본:
ARCHITECTURE.md — 단일 파일로 시작
- 분리 후:
ARCHITECTURE-{AREA}.md (예: ARCHITECTURE-FRONTEND.md, ARCHITECTURE-LAMBDA.md)
- 공통 파일: 분리 후에도 영역 간 공통 내용(연결 방식, 공유 인프라 등)이 있으면
ARCHITECTURE.md 유지, 없으면 삭제
목적
AI 에이전트가 코드를 작성할 때 가장 많은 토큰을 소비하는 원인은 탐색·추측·되돌아오기다.
이 스킬은 에이전트가 탐색 없이 바로 작업에 들어갈 수 있도록 다음을 제공한다:
- 구조 (Structure): 파일과 폴더가 어디에 있는지
- 흐름 (Flow): 데이터·요청이 어떤 경로로 이동하는지
- 경계 (Boundary): 수정해도 되는 곳과 금지된 곳
전체 흐름
Step 1: 기존 파일 확인 (현재 모드 파악)
↓
Step 2: 영역 감지 및 분석
↓
Step 3: 분리 필요 여부 결정 및 실행
↓
Step 4: 파일 작성 또는 갱신
↓
Step 5: 공통 파일(ARCHITECTURE.md) 관리
↓
Step 6: 파일 압축 검토
↓
Step 7: 결과 표시
Step 1: 기존 파일 확인
프로젝트 루트에서 다음을 확인해 현재 모드를 파악한다:
ARCHITECTURE.md 존재 여부 → 단일 파일 모드 또는 분리 후 공통 파일ARCHITECTURE-*.md 패턴의 파일 목록 → 분리 모드
파일이 있으면 각 파일의 내용을 읽고 기존 구조와 ## Notes 섹션을 확인한다.
Step 2: 영역 감지 및 분석
감지 규칙은 references/stack-detection.md를 따른다.
파일 형식은 references/architecture-file-format.md를 참고한다.
2-0. 영역(Area) 감지
루트 하위 디렉터리를 스캔해 독립적인 프로젝트 영역을 식별한다.
영역으로 간주하는 기준 (하나 이상 충족):
- 해당 디렉터리에 빌드/패키지 파일(
package.json, pyproject.toml, build.gradle.kts 등)이 있다
- 명확히 분리된 관심사를 가진 루트 디렉터리다 (
frontend/, backend/, lambda/, api/ 등)
영역명: 디렉터리명 대문자 (예: frontend/ → FRONTEND)
2-1. 스택 및 디렉터리 구조
각 영역(또는 단일 프로젝트 전체)에 대해:
- 빌드/패키지 파일로 스택을 감지한다
- 주요 경로와 역할을 2~3 depth로 수집한다 (진입점 명시, 수정 금지 폴더 표시)
- 빌드 산출물,
node_modules 등은 포함하지 않는다
2-2. 데이터 흐름
데이터·요청이 이동하는 핵심 경로를 파악한다:
- 프로세스 간 통신 방식 (HTTP, IPC, gRPC 등)
- 레이어 간 호출 순서 (Router → Service → Repository 등)
- 자동 생성 파이프라인
화살표(→)로 단방향 흐름을 표현하고 수정 금지 파일은 [수정 금지]로 표시한다.
2-3. 레이어 아키텍처
레이어 이름과 역할 한 줄 요약, 레이어 간 의존 규칙을 정리한다.
2-4. 경계 (Boundary)
수정하면 안 되는 파일/폴더와 그 이유, 대안을 표로 정리한다.
모호한 경우
영역 구분이 불확실하거나 구조 파악이 어려우면 바로 질문한다. PAUSE.
Step 3: 분리 필요 여부 결정 및 실행
현재 단일 파일 모드인 경우
분리 실행 기준 (모두 충족해야 함):
ARCHITECTURE.md 단일 파일이 존재한다- 독립 영역이 2개 이상 감지된다
- 각 영역이 자체 빌드/패키지 파일을 갖거나 서로 다른 기술 스택을 사용한다
- 각 영역의 내용이 단순 경로 목록 수준을 넘어 독자적인 구조·흐름을 가진다
기준을 충족하면 분리를 실행한다:
- 기존
ARCHITECTURE.md의 내용을 영역별로 분류한다
- 각 영역에 해당하는 내용을 추출해
ARCHITECTURE-{AREA}.md 생성 준비를 한다
- 원본 파일은 Step 5에서 처리한다
기준을 충족하지 않으면 단일 파일 모드를 유지한다 (Step 4로 이동).
현재 분리 모드인 경우
분리 단계를 스킵하고 Step 4로 이동한다.
Step 4: 파일 작성 또는 갱신
파일 형식은 references/architecture-file-format.md를 따른다.
단일 파일 모드: ARCHITECTURE.md를 작성 또는 갱신한다.
분리 모드: 각 영역의 ARCHITECTURE-{AREA}.md를 작성 또는 갱신한다.
- 기존 파일이 있는 영역은 분석 결과를 기준으로 갱신한다
- 새로 감지된 영역은 새 파일을 생성한다
- 사라진 영역의 파일은 삭제한다
공통 규칙:
- 기존
## Notes 섹션이 있으면 유지한다
- 간결하게 유지한다 (에이전트가 탐색 없이 파악할 수 있는 수준이면 충분)
- 장황한 배경 설명·히스토리·TBD 항목은 포함하지 않는다
Step 5: 공통 파일(ARCHITECTURE.md) 관리
분리 모드에서만 이 단계를 실행한다.
공통 내용으로 간주하는 기준:
- 영역 간 통신 방식 (예: Frontend → Backend HTTP, Backend → Lambda 호출)
- 여러 영역이 공유하는 인프라 (공유 DB, 메시지 큐, 공통 인증 등)
- 어느 영역 파일에도 속하지 않는 전체 시스템 개요
판단 및 처리:
- 공통 내용이 있으면
ARCHITECTURE.md를 유지하거나 새로 작성한다 (공통 내용만 포함)
- 공통 내용이 없으면
ARCHITECTURE.md를 삭제한다
- 분리를 막 실행한 경우, 기존 단일 파일에서 공통 내용을 추출 후 나머지는 삭제한다
Step 6: 파일 압축 검토
작성 또는 갱신된 각 파일을 다음 기준으로 검토하고 압축한다.
- 이모지·아이콘 제거 — 파일 본문에 포함된 이모지(✅, 💡, ⚠️ 등)는 모두 제거한다
- 중복 표현 통합 — 동일한 내용이 여러 섹션에 반복되면 한 곳에만 남기고 나머지는 삭제한다
- 자명한 설명 제거 — 디렉터리 이름·파일 이름만 봐도 알 수 있는 주석은 생략한다
- 빈 섹션 제거 — 내용이 없는 섹션은 제목까지 삭제한다
- 과도한 세부 사항 축약 — 에이전트가 작업에 필요한 수준을 넘는 설명은 한 줄로 줄이거나 삭제한다
Step 7: 결과 표시
완료 후 짧게 표시한다:
아키텍처 동기화 완료
생성/갱신: ARCHITECTURE-FRONTEND.md, ARCHITECTURE-LAMBDA.md
삭제: ARCHITECTURE.md (공통 내용 없음)
변경이 없으면:
아키텍처 파일이 이미 최신입니다.
참조 파일
| 파일 | 사용 시점 |
|---|
references/stack-detection.md | Step 2 영역·스택 감지 시 |
references/architecture-file-format.md | Step 4 파일 작성/갱신 시 |
