출력 스타일 (평범한 말, 대시나 하이픈 없음)
이 스킬이 생성하는 모든 것(파일과 메시지 모두)은 평범하고 간단한 언어로 작성하세요. 독자에게 당신이라고 따뜻하고 직접적으로 동료처럼 말하며, 모든 단계를 명령이 아닌 실행하거나 건너뛸 수 있는 권장 사항으로 제시하세요. 실제 의미를 지닌 기술 용어는 유지하되 각각을 평범한 말로 설명하세요. 문장 부호로 대시나 하이픈을 절대 사용하지 마세요: em 대시, en 대시, 하이픈으로 연결된 복합어도 안 됩니다. read-only 대신 read only라고 쓰세요. 간단한 말로 표현하거나 문장을 다시 작성하세요. 코드, 파일 경로, 명령 플래그, 다른 스킬이 매칭하는 값은 하이픈을 유지합니다. 짧은 문장, 쉼표, 괄호를 사용하세요. 명확함이 재치보다 중요합니다.
이 스킬이 하는 일
완료된 변경의 루프를 닫습니다: AGENTS.md 파일, 범위, 연결된 사양의 **Status**: 라인을 저장소가 현재 보여주는 상태와 동기화하고, 편집해서는 안 되는 것(오래된 사양, 선별된 산문)을 플래그로 표시합니다. 아래 경계 테이블이 정확한 계약입니다.
**agent-prompt.md**는 유지 관리 규칙의 단일 진실 공급원입니다; SKILL.md는 오케스트레이션만 다룹니다. 메인 스레드가 이를 읽고 유지 관리를 직접 수행합니다(3단계 참조).
표준 파일: 내구성 있는 컨텍스트는 도구에 구애받지 않는 **AGENTS.md**에 있습니다; CLAUDE.md는 단지 포인터일 뿐입니다. /sync는 둘 다 편집/생성하지만, 변경 소스가 아닌 대상으로만 취급합니다.
경계
| 작업 | /sync | 소유자 |
|---|---|---|
| 기존 루트/중첩 AGENTS.md 편집 | ✅ 유지 | /sync |
루트 AGENTS.md의 ## Build approach 라인을 범위 헤더의 접근 방식과 조정 (스택처럼 수술적인 단일 라인 편집) | ✅ 유지; 편차가 있으면 플래그 | /sync |
변경이 UI 디자인 시스템을 확립할 때 가장 가까운 AGENTS.md에 design.md에 대한 한 줄 포인터 추가 (포인터만) | ✅ 유지 (포인터만) | /sync |
이 변경에서 처음 등장한 영역에 대해 중첩된 <area>/AGENTS.md 생성 (diff = 전체 영역 컨텍스트) + 루트 포인터 추가 | ✅ 생성 | /sync |
| 이미 존재하는 문서화되지 않은 영역에 대한 중첩 문서 생성 (diff로 조각만 보일 때) | ❌ "/audit 실행" 플래그 | /audit |
| 루트 AGENTS.md 생성 또는 재구성 | ❌ "/audit 실행" 플래그 | /audit |
사양의 **Status**: 라인을 해당 기능의 범위 상태와 조정 (planned→Proposed, in-progress→In Progress, done→Accepted; Assumed 사양은 예외: Assumed로 두고 표면화하며, 절대 Accepted로 조정하지 않음) | ✅ 상태 라인만 | /sync |
Assumed 사양 정리 ( Assumed에서 이동) | ❌ 결정 부채로 플래그 "/architect 실행하여 비준" (기능 상태로 절대 조정되지 않음; 비준만이 정리함) | /architect |
| 사양의 내용 편집 / 대체 | ❌ 오래됨으로 플래그 | /architect |
관련 작업공간의 범위 파일만 (전체 docs/scope/ 아님), 저장소 증거(코드, 테스트, AGENTS.md)에서 완료된 하위 작업 체크, 상태 업데이트 | ✅ 수정 | /sync |
| 범위에 기능 또는 하위 작업 추가 / 재정렬 | ❌ 그대로 둠 | /scope |
| 선별된 AGENTS.md 산문 덮어쓰기 또는 재작성 | ❌ 대신 충돌 플래그 | 사람 |
생성의 기준선은 정책이 아닌 컨텍스트입니다: 이 변경이 전체 영역을 보여줄 때만 생성하고, 영역이 변경보다 먼저 존재하고 조각만 보일 때는 /audit에 위임하세요. 확실하지 않으면 생성 대신 플래그를 표시하세요.
요청 vs 실행
실행합니다. 동기화할 것이 없을 때만(빈 변경 세트) 멈춥니다. 선별된 파일에 대한 모든 편집은 보고서에 나열되어 검토 또는 되돌릴 수 있습니다.
산출물 소유권
경계 테이블이 부여한 것만 정확히 소유하며, 그 외에는 아무것도 쓰지 않습니다. 보편적인 하위 작업 조정자로서 저장소 증거(다른 스킬이 체크하지 않는 /test//audit//sync 하위 작업을 훑음)로 확인할 수 있는 모든 범위 하위 작업을 체크하고 기능 상태를 업데이트합니다; 정확한 규칙은 agent-prompt.md에 있습니다.
산출물 기준. 사양과 범위는 기본적으로 docs/ 아래에 있거나, docs/가 게시된 문서 사이트인 경우 .workflow/ 아래에 있습니다; 저장소에 존재하는 기준을 사용하세요(여기서 경로는 docs/를 가정합니다).
이식성 (모든 OS, 모든 에이전트)
- 명령어:
git은 유일하게 필요한 CLI이며 모든 OS에서 동일하게 동작합니다. 표시된 대로git라인을 실행하세요. 다른 셸 스니펫은 POSIX 참조일 뿐, 문자 그대로의 스크립트가 아닙니다:find,grep,sed,cat,test/[ ],ls,xargs가 존재한다고 가정하지 마세요; 에이전트의 크로스 플랫폼 파일 도구를 사용하고 셸if/변수/리디렉션 대신 직접 분기 로직을 적용하세요. - 번들 파일: 이 스킬 폴더에 대한 상대 경로로 참조됩니다. 폴더를 절대 경로로 확인하고(이미 이러한 상대 경로를 확인함) 이전 단계가 아닌 쓰기 시간(3단계)에
agent-prompt.md를 직접 읽으세요. - 전체 유지 관리는 메인 스레드에서 인라인으로 실행되며,
agent-prompt.md(권위 있음)의 정확한 규칙을 따릅니다.
실행
1. 변경 세트 범위 지정 (저렴하며, 파일별 상태 포함)
먼저 최신 상태로(팀): git fetch --quiet; git rev-list --count HEAD..origin/$BASE > 0이면 origin/$BASE보다 뒤쳐진 것이므로 엔지니어에게 먼저 풀을 요청하세요. 팀원이 이미 이 문서들을 동기화했을 수 있습니다.
기준: git rev-parse --verify main이 성공하면 main, 아니면 master. 현재 브랜치: git rev-parse --abbrev-ref HEAD. --name-only가 아닌 --name-status를 사용하세요; 새 영역과 고아 정리 로직은 파일당 Added vs Modified vs Deleted가 필요합니다.
- 현재 브랜치가 기준과 같음, 모드
uncommitted:git diff --name-status HEAD. - 그 외, 모드
branch:git merge-base "$BASE" HEAD, 그런 다음git diff --name-status <merge-base>.
어느 쪽이든, git ls-files --others --exclude-standard에서 추적되지 않은 파일을 추가하고, 각각에 A 상태 접두사를 붙입니다(--name-status 형식과 일치). 모드, 기준, 병합 기준을 쓰기 단계를 위해 기록하세요.
중복을 제거한 다음, 동기화 할 소스 파일로 필터링:
- 문서 및 설정 제거 (모든 수준의
AGENTS.md,docs/**,*.md,test-preferences.json, 잠금 파일, 생성된 출력); /sync는 이것들을 대상/컨텍스트로 읽으며, 변경 소스로 절대 읽지 않습니다. - 테스트 파일 제거 (
*.test.*,*.spec.*,__tests__/등); 테스트는 내구성 있는 영역 규칙이 아닙니다. D(삭제됨) 항목을 별도 목록에 보관합니다. 3단계에서 고아 정리를 유도하지만, 소스로 동기화되지는 않습니다.- 종속성 매니페스트 변경 사항을 도구 발견을 위해 별도 목록에 보관합니다. 설정 파일이더라도 마찬가지입니다:
package.json,pyproject.toml,requirements*.txt,go.mod,Cargo.toml,composer.json,Gemfile,pubspec.yaml,mix.exs,*.csproj및 동등한 패키지 매니페스트. 잠금 파일은 신호일 뿐입니다; 잠금 파일 내용을 전달하지 마세요.
소스 파일과 종속성 매니페스트 변경 사항이 모두 없는 경우(문서/테스트/잠금/생성된 파일만 변경됨), 중지합니다. 동기화할 것이 없습니다. 실행하지 마세요.
2. 컨텍스트 파일 및 사양 찾기 (경로만, 여기서 읽지 마세요)
에이전트의 파일 검색/글로브 도구 사용:
- 루트
AGENTS.md가 존재하는지 확인합니다. node_modules/와.git/를 제외한 모든AGENTS.md(루트 + 중첩)를 찾습니다.docs/specs/아래에서 이름이 숫자로 시작하는 모든 사양을 정렬하여 찾습니다.- diff가 실제로 건드리는 작업공간/기능의 범위 파일을 찾습니다(모노레포에서 변경된 파일의 작업공간
apps/<x>/…이docs/scope/<x>/를 선택합니다);docs/scope/전체를 절대 읽거나 전달하지 마세요.
경로와 변경된 파일 목록 및 diff 명령어를 기록하고, 쓰기 시간에 파일을 읽습니다. 지금 루트 AGENTS.md 내용을 읽습니다(짧고 고정점에 유용). 각 변경된 파일에 대해, AGENTS.md(루트 또는 중첩)가 있는 가장 가까운 상위 디렉토리를 기록합니다; 이것이 업데이트가 가장 필요할 수 있는 컨텍스트 파일입니다.
2.5 새로 추가된 도구에 대한 Agent Skill 및 선택적 MCP 발견
종속성 매니페스트가 변경되었거나 diff가 중요한 외부 도구를 명확히 추가한 경우에만 실행하세요. 내구성 있는 워크플로우나 통합을 정의하지 않는 한 일반 유틸리티 라이브러리는 건너뛰세요.
-
전체 잠금 파일이 아닌 매니페스트 diff에서 새로 추가된 중요한 패키지/도구를 식별하세요: 프레임워크, 라우터, 스타일링/UI 키트, 데이터베이스, ORM/쿼리 레이어, 인증/세션, 결제, 이메일/알림, 스토리지/업로드, 검색, 큐/백그라운드 작업, AI 제공자/벡터 DB, 브라우저/런타임 테스트, 관측 가능성, 호스팅/배포. 매니페스트에서 패키지 이름과 일반적인 별칭을 포함하세요. 첫 번째 기술에서 멈추지 마세요.
-
이미 설치된 스킬, 연결된 MCP, 또는
AGENTS.md에서 거부된 항목으로 이미 다루어지는 것은 필터링하세요. -
검색하기 전에 물어보세요.
질문은 필수입니다. 검색은 필수가 아닙니다. 엔지니어가 선택할 때까지 Agent Skill 및 MCP 발견을 위해 아무것도 검색, 가져오기, 설치 또는 생성하지 않습니다. 네 가지 선택지를 제공하세요: 저를 위해 찾아주세요, 제가 원하는 것을 말하겠습니다, 아니요 그리고 거부를 기록합니다, 나중에. 첫 번째만 검색 명령을 실행할 수 있습니다. 조용히 제안을 건너뛰지 말고, 엔지니어가 동의하기 전에 검색을 절대 실행하지 마세요.
이 변경이 추가한 도구의 이름을 말하고, Agent Skill이 에이전트에게 그 도구의 실제 규칙을 제공하고 MCP 서버가 실제 시스템에 대한 라이브 액세스를 제공한다고 한 줄로 설명한 다음, 물어보세요: "이 변경이 추가한 도구에 대한 Agent Skill과 MCP 서버를 찾을까요?" (헤더
Agent skills),네, 찾아주세요(권장) ·제가 원하는 것을 말하겠습니다·아니요, 건너뛰세요·지금은 안 됩니다, 나중에.네인 경우 아래를 계속합니다.제가 원하는 것을 말하겠습니다인 경우 목록을 받아 설치 단계로 바로 이동하며, 아무것도 검색하지 않습니다.아니요, 건너뛰세요인 경우 아무것도 실행하지 않고 거부를 기록합니다.지금은 안 됩니다, 나중에인 경우 아무것도 실행하지 않고 보고서에 후보 도구를 기록합니다. -
검색을 읽기 전용 하위 에이전트로 격리하세요(먼저 기능 확인 후,
네인 경우에만). 나머지 세트를 메인 스레드에서 검색하는 대신 발견 하위 에이전트에 넘기세요: 에이전트가 지원한다면 백그라운드에서 생성하고(차단하지 않음), 그렇지 않으면 차단; 모델을 명시적으로 빠르고 저렴한 계층으로 설정하고(세션 모델을 상속하지 않음; Claude Code에서는 모델을 고정하는researcher하위 에이전트 유형으로 생성); 컴팩트한 후보 목록만 반환합니다. 이렇게 하면 검색 출력이/sync의 경계된 컨텍스트 밖에 유지됩니다. 하위 에이전트가 없으면 인라인 검색; 검색 기능이 없으면 건너뛰고 기록합니다. 제안 패널은 메인 스레드에 유지됩니다. -
각 남은 항목에 대해
npx skills find <tool-or-package>를 실행합니다; 약하면 패키지/조직 이름에서 별칭을 다시 시도합니다. 모든 신뢰할 수 있는 Agent Skill 후보를 수집하고 가능할 때npx skills add <owner>/<repo> --list로 확인합니다. CLI가 대화형이거나 사용 불가능하면"<tool>" "agent skill"을 검색하고 제공하기 전에 확인합니다. -
MCP 검색은 선택 사항입니다: 먼저 커넥터 목록, 그 다음 항목당
"<tool>" "MCP server". MCP는 권장되는 추가 이점이지 필수가 아닙니다. -
발견을 제한하고 캐시 가능하게 유지하세요: 최대 5개의 웹 검색과 총 8개의 가져온 페이지, 공식 레지스트리/문서 먼저. 설치된/거부된 항목을 필터링한 후, 30일 미만이면
docs/.agent-cache/tool-discovery/<slug>.md를 재사용하세요. -
모든 Agent Skill 일치 항목을 기술별로 그룹화하여 하나의 다중 선택 패널로 제공하세요: "새로 추가된 도구에 대한 관련 Agent Skill을 설치할까요?" 더하기 건너뛰기/거부. 그런 다음 MCP를 별도로 제공하세요: "이 도구에 도움이 될 수 있는 선택적 MCP 서버" 더하기 건너뛰기/거부. 자동으로 설치하거나 연결하지 마세요.
-
선택한 스킬을
npx skills add <owner>/<repo> -y로 설치하세요. MCP의 경우 사용자의 커넥터/MCP 설정을 가리키세요; 연결되면 도구가 자동으로 사용됩니다. -
결과를
INSTALLED_SKILLS_OR_NONE,MCP_SERVERS_OR_NONE,DECLINED_TOOLS_OR_NONE으로 전달하고, 쓸 때 올바른AGENTS.md파일에 내구성 있는 라인을 기록하세요. 찾은 것이 없거나 기능이 없으면none으로 처리하세요.
3. 유지 관리 수행 (메인 스레드)
메인 스레드가 유지 관리를 직접 수행합니다. AGENTS.md / 범위 / 사양 상태 편집을 하위 에이전트에 넘기지 않습니다. 지금(쓰기 시간에만) agent-prompt.md를 읽고 정확히 따르세요; 유지 관리 규칙에 대해 권위 있습니다. diff 읽기는 대규모 변경 세트의 경우에만, 가장 저렴한 모델(Claude Code: haiku)의 읽기 전용 scout 하위 에이전트에 오프로드할 수 있으며, 컴팩트한 맵을 반환합니다. 이전 도구 권한이 표현한 것과 동일한 경계 내에 머무르세요: 기존 문서, 범위, 사양 **Status**: 라인 Edit; 완전히 새로운 영역 중첩 AGENTS.md에 대해서만 Write; 루트 생성 금지, 사양 내용 편집 금지(상태 라인만), 기존 영역에 대한 얕은 중첩 문서 금지(이것들은 agent-prompt.md의 규칙입니다).
적용할 입력:
MODE,BASE,MERGE_BASE,CHANGED_FILES(이름 상태 변경된 소스 목록),DIFF_COMMAND(정확한git diff명령어)DELETED_PATHS(삭제된 경로, 고아 정리용)ROOT_AGENTS_MD(루트 AGENTS.md 내용),NESTED_PATHS(중첩 AGENTS.md 경로)SPEC_PATHS(모든 사양 경로, 상태 라인 조정 및 구식 플래그용)FILE_TO_CONTEXT_MAP(변경된 파일 → 가장 가까운 컨텍스트 파일)SCOPE_PATH_OR_NONE(관련 작업공간 범위 경로, 전체docs/scope/아님; 연결된 각 기능의 상태 소스이기도 함, 사양 상태 라인 조정용)- 2.5단계의
INSTALLED_SKILLS_OR_NONE,MCP_SERVERS_OR_NONE,DECLINED_TOOLS_OR_NONE
4. 결과 전달
유지 관리가 실패했거나 구문 분석 가능한 요약을 생성하지 못한 경우, 그것을 보고하고 다시 수행하세요. 결과를 조작하지 마세요(진정한 NOTHING_TO_SYNC는 유효한 성공입니다; 충돌 또는 빈 출력은 그렇지 않습니다). 그렇지 않으면 컴팩트한 요약을 전달하세요:
한 줄로 조정한 내용을 먼저 제시합니다; 그런 다음 엔지니어가 필요한 것만 나열합니다(docs/conventions.md에 따라). 편집 내용 자체는 파일에 있습니다. 템플릿:
## /sync 완료 · <N>개 변경 파일 조정됨
**<AGENTS.md 파일 · 범위 기능 · 사양 상태>를 diff와 일치하도록 업데이트했습니다.** (또는 "모든 것이 이미 최신이며, 동기화할 것이 없음")
참고 사항 (당신이 필요합니다):
- 오래된 사양 → /architect: `<file>` (<이유, 또는 /sync가 안전하게 다시 쓸 수 없는 상태 불일치>