WoJiSama/skill-based-architecture

English | 中文

AI 에이전트 규칙 시스템을 위한 라이프사이클 프레임워크 (lifecycle framework). 흩어져 있는 프롬프트 문서들(AGENTS.md, CLAUDE.md, .cursor/rules/, README 규칙들)을 skills/<name>/ 하위의 라우팅 가능하고(routable), 검증 가능하며(verifiable), 업데이트 가능한(updatable) 엔지니어링 자산으로 전환합니다.

이 프레임워크는 규칙 시스템 자체, 즉 구조(structure), 라우팅(routing), 워크플로우(workflows), 검증(validation), 사후 행동 학습(after-action learning), 그리고 상류/하류 업데이트(upstream/downstream updates)에 집중합니다. 특정 기술에 종속된 규칙(technology-specific rules)을 제공하지는 않습니다. 그러한 규칙들은 귀하의 하류 프로젝트 스킬(downstream project skill)에 속해야 합니다.

scattered project guidance
AGENTS.md / CLAUDE.md / .cursor/rules / README notes
│
...

증상	발생하는 문제
400줄 이상의 단일 SKILL.md	에이전트가 매 작업마다 모든 내용을 읽음 — 토큰(tokens) 낭비, 중요한 내용이 가려짐
AGENTS.md, .cursor/rules/, CLAUDE.md에 규칙이 중복됨	드리프트(Drift), 모순 발생, 단일 진실 공급원(source of truth) 부재
스킬 활성화(Skill activation)가 신뢰할 수 없음	설명(Description)이 명시적인 트리거 조건(trigger conditions) 대신 수동적인 요약으로 작성됨
어렵게 얻은 교훈이 문서에 묻힘	값비싼 실수(pitfalls)가 다음 작업 중에 드러나지 않음
규칙 파일이 줄어들지 않고 계속 늘어남	유용한 규칙이 쓸모없어진 규칙들에 의해 묻힘

이 아키텍처는 각각의 문제에 대한 해답을 제시합니다: 라우팅 진실 공급원(routing.yaml), 그 외 모든 곳에서의 얇은 셸(thin shells), 트리거로서의 설명(description-as-trigger) 원칙, 기록 임계값(recording threshold)을 가진 사후 행동 검토(AAR), 그리고 라인 수 신호(line-count signals)와 분할/병합 절차를 통한 자가 유지보수(self-maintenance)입니다.

• 총 규칙 내용 < 50줄 (단일 CLAUDE.md로 충분함) - 단일 하네스(harness), 팀 공유 없음, 반복 작업 없음
• 단기적인 개인 프로젝트 (< 2주)

일반적인 CLAUDE.md 또는 .cursor/rules/workflow.mdc로 시작하세요. 콘텐츠가 방대해지면 나중에 업그레이드하면 됩니다. WORKFLOW.md에는 해당 업그레이드를 위한 빠른 시작(Quick Start) 경로가 포함되어 있습니다.

이 저장소를 원하는 어떤 방식으로든 (git clone, zip 다운로드, 서브모듈, 포크 등...) 어느 위치에든 가져오세요. 유일한 요구 사항은 귀하와 에이전트 모두 해당 위치를 알고 있어야 한다는 점입니다.

에이전트가 트리거되었을 때 이 디렉터리를 찾을 수만 있다면 경로는 중요하지 않습니다. 만약 에이전트의 기본 검색 경로(예: Cursor의 ~/.cursor/skills/, .cursor/skills/ 또는 프로젝트 자체의 skills/)에 없다면, 에이전트가 찾을 수 있도록 CLAUDE.md / AGENTS.md / .cursor/rules/에 해당 경로를 작성하세요.

일반적인 배치 위치:

• 프로젝트 내부:
  skills/skill-based-architecture/

• 프로젝트 옆:
  ../skill-based-architecture/

• Cursor 사용자 레벨:
  ~/.cursor/skills/skill-based-architecture/

• Cursor 프로젝트 레벨:
  .cursor/skills/skill-based-architecture/

예시 (프로젝트 내부에 클론):

git clone https://github.com/WoJiSama/skill-based-architecture.git \
skills/skill-based-architecture

에이전트에게 로컬 메타 스킬 (meta-skill)을 사용하도록 요청하세요:

"Use skill-based-architecture to refactor the project rules"

동일한 의미의 트리거: "Organize the project rules", "Migrate rules to skills/", "整理项目规则".

그러면 에이전트는 templates/에서 미리 구축된 스캐폴드 (scaffold)를 skills/<name>/로 복사하고, 얇은 쉘 (thin shells)을 생성하며, 모든 <!-- FILL: --> 마커를 채운 뒤 검증을 실행합니다. 전체 절차는 WORKFLOW.md를 참조하세요.

이 메타 스킬의 여러 워크플로 (workflows)는 서브 에이전트 위임 (sub-agent delegation) 및 병렬 에이전트 팬아웃 (parallel agent fan-out)에 의존합니다 (templates/skill/workflows/subagent-driven.md 및 templates/skill/workflows/refactor-fanout.md 참조). 대부분의 하네스 (harnesses)에서는 저장소 내의 규칙만으로 충분하며, 에이전트가 스스로 언제 팬아웃을 할지 결정합니다.

Codex는 예외입니다. Codex의 런타임 (runtime)은 spawn_agent에 대해 도구 레벨 규칙 (tool-level rule)을 부과합니다. 즉, 사용자가 서브 에이전트, 위임 또는 병렬 에이전트 작업을 명시적으로 요청할 때만 호출될 수 있습니다. 이 도구 레벨 규칙은 이 저장소의 AGENTS.md나 스킬 파일에 있는 그 어떤 것보다 우선하므로, 워크플로 문서가 에이전트에게 이를 사용하라고 지시하더라도 팬아웃 패턴이 자동으로 실행되지 않습니다.

만약 Codex를 사용 중이고 서브 에이전트 작업(팬아웃 또는 기타 작업)이 실제로 일어나기를 원한다면, 명시적으로 권한을 부여해야 합니다. 두 가지 동일한 패턴은 다음과 같습니다:

작업별 (Per-task) — 위임하고자 하는 구체적인 작업을 명시합니다:

"sub-agent를 사용하여 규칙 파일들을 리팩토링하세요." "각 워크플로우 파일을 병렬로 검토하기 위해 sub-agent들을 생성하세요." "请使用 sub-agent 来扫一遍 templates 目录 (sub-agent를 사용하여 templates 디렉토리를 한 번 훑어보세요)."

세션 전체 (Session-wide) — 시작 시점에 포괄적인 권한을 한 번 부여합니다:

"이번 세션에서는 워크플로우가 필요로 할 때마다 sub-agent를 사용할 수 있습니다." "本次会话我允许你使用 sub-agent (이번 세션에서 당신이 sub-agent를 사용하는 것을 허용합니다)." "이번 세션 동안 자유롭게 sub-agent에게 위임하세요."

두 형태 모두 도구 수준의 규칙(tool-level rule)을 충족합니다. 이 중 하나가 없다면, 워크플로우 문서에서 에이전트에게 sub-agent를 사용하라고 지시하더라도 Codex는 위임 단계를 조용히 건너뛸 것입니다.

이중 계층 라우팅 (Two-layer routing). SKILL.md는 생성된 짧은 항상 읽기 (Always Read) 목록을 유지하며, Common Tasks는 필요할 때만 에이전트를 추가 파일로 라우팅합니다. routing.yaml은 하위 프로젝트에서 편집 가능한 신뢰할 수 있는 단일 원천 (source of truth)입니다.

라우팅을 포함한 얇은 쉘 (Thin shells with routing bootstrap). 모든 엔트리 파일은 routing.yaml을 가리키는 짧은 부트스트랩 (bootstrap)을 내장합니다. 라우팅 테이블은 여러 쉘에 걸쳐 중복되지 않습니다. 자연어 전용 지침은 컨텍스트 요약 (context summarization) 과정에서 유실될 수 있습니다.

트리거 조건으로서의 설명 (Description as trigger condition). 워크플로우 키워드 채우기 방식이 아닌, 사용자의 실제 언어로 된 도메인 수준의 활성화 문구를 사용합니다. 편집 후에는 소리 내어 다시 읽어보세요. 실제 사용자처럼 들리는지 확인하는 데에는 스크립트보다 직접 듣는 것이 가장 확실합니다.

세션 규율 + 작업 종료 (Session Discipline + Task Closure). 동일 세션 내의 모든 새로운 작업 시 SKILL.md를 다시 읽습니다. 사소하지 않은 작업은 30초간의 사후 검토 (AAR, After Action Review) 스캔과 기록 임계값을 통해 마무리하며, 절대 "테스트 통과 = 완료"로 간주하지 마세요.

자가 유지보수 (Self-maintenance). 라인 수 신호는 자동 작업이 아닌 평가를 트리거합니다. 분할/병합 절차와 최신성 확인을 통해 문서를 간결하게 유지합니다.

교차 하네스 (Cross-harness). Cursor, Claude Code, Codex, Windsurf, Gemini, OpenCode, 그리고 AGENTS.md 기반 도구들과 호환됩니다.

도구 (Tool)	필수 항목 (Required entry)
Cursor	.cursor/skills/<name>/SKILL.md + .cursor/rules/*.mdc
Claude Code	CLAUDE.md (선택 사항: .claude/skills/<name>/SKILL.md stub)
Codex CLI / Copilot CLI / OpenCode / 기타	AGENTS.md
Windsurf	.windsurf/rules/*.md 또는 공유된 AGENTS.md
Gemini CLI	GEMINI.md

모든 항목에는 routing.yaml이 포함되어야 합니다.

bootstrap — Claude Code 네이티브 스킬(native skills)의 경우, 기업(enterprise) > 개인(personal) > 프로젝트(project) 우선순위에 따라 동일한 이름의 스킬이 해결되므로 프로젝트 전용 이름(<project>-review)을 사용하는 것이 좋습니다.

도구별 템플릿: references/per-tool-shells.md.

도구 호환성 심층 분석: 동일 파일.

파일	내용
SKILL.md	스킬 항목: 사용 시점, 대상 구조, 핵심 원칙
...

이것이 Anthropic의 공식 스킬 템플릿을 대체합니까?
아니요. 공식 템플릿은 최소한의 스킬 형태(SKILL.md와 프론트매터(frontmatter)가 포함된 폴더)를 정의합니다. 이 메타 스킬(meta-skill)은 한 단계 더 나중에 시작됩니다. 즉, 단일 소규모 SKILL.md만으로는 충분하지 않을 때 구조를 추가해 줍니다.

점진적으로 마이그레이션(migrate)할 수 있습니까?
네. 1단계: 규칙(rules) 추출. 2단계: 워크플로(workflows) 추출. 3단계: 참조(references)를 추출하고 얇은 셸(thin shells) 생성. 각 단계마다 프로젝트는 작동 가능한 상태로 유지됩니다.

하위 프로젝트(downstream projects)는 상위 프로젝트(upstream)의 개선 사항을 어떻게 전달받습니까?
에이전트(agent)에게 상위 프로젝트로부터 업데이트하도록 요청하십시오. 복사된 workflows/update-upstream.md는 최신 상위 프로젝트를 클론(clone)하고, 클론된 저장소의 UPSTREAM-CHANGES.md를 읽으며, 스스로 파일을 비교하고, 메커니즘 변경 사항을 패치(patch)하며, 프로젝트 소유 콘텐츠를 보존하고, 상위 프로젝트 자체의 계약(contract)에 대한 준수 여부를 포함하여 검증(validation)을 다시 실행합니다.

Learn AI on LinuxDO — LinuxDO