미션 (에이전트용)
이 저장소는 성장 지향적인 에이전트 하네스입니다. 모든 작업은 시스템 자체를 개선할 기회입니다. 하지만 무언가를 추가할 때는 그것이 반드시 목적에 부합하고 그것을 제공하는 가장 좋은 방법일 때만 추가하십시오. 비대화는 첫 번째 실패입니다: 기존 명령어를 감싸는 래퍼, 다른 문서를 반복하는 문서, 호출자가 하나뿐인 CLI 등입니다. 새로운 것을 추가하기 전에 스스로에게 물어보십시오: 이 기능이 이미 존재하는가? 단순한 rg / cat / touch로 충분한가? 그렇다면 추가하지 마십시오.
기억할 만한 것을 발견하면 af note로 추가하거나 research/lessons/에 직접 파일을 생성하십시오. 리서치 스킬은 시스템이 스스로 학습할 수 있도록 존재합니다. 추측에 의존하기 전에 먼저 사용하십시오.
아키텍처 변경을 계획하기 전에 에이전트 지식을 참조하십시오
research/knowledge/는 프로젝트의 장기 기억입니다. research/(논문, 프로젝트, 문서, 교훈)에 있는 모든 것을 정제한 결과물입니다. 하네스, 오케스트레이션 또는 스킬 시스템을 변경하기 전에 이미 연구된 내용을 확인하십시오:
af ak list # research/knowledge/ 페이지 색인
af ak show <slug> # 한 페이지 읽기
af ak grep "<pattern>" # knowledge/ 내 전체 텍스트 검색
rg "<pattern>" research/ # 전체 연구 트리 검색 (원시 입력 포함)
af archetype match "<user intent>" # 이 작업이 알려진 형태와 일치하는가?
이미 지식 페이지가 내용을 다루고 있다면, 재발견하지 말고 그 위에 구축하십시오. 교훈이 당신이 하려는 것과 모순된다면 멈추고 조정하십시오.
주간 개선 루틴
자기 개선 장치는 누군가 실행할 때만 효과를 발휘합니다. af log review + af skill-usage summary를 매주 예약하고(cron 또는 달력 알림) 출력에 따라 행동하십시오:
# ~/.config/systemd/user/... 또는 crontab -e
0 9 * * 0 /home/you/.local/bin/af log review >> ~/.claude/logs/reviews/$(date +\%F).md
검토 후 다음을 훑어보십시오:
~/.claude/logs/observations.md—af log review가 작성한 이상 징후와 교훈. 반복되는 패턴이 있으면 스킬 편집 또는 지식 페이지로 승격시키십시오(research/knowledge/README.md의 승격 규칙 참조).af skill-usage summary— "한 번도 로드되지 않음" 목록은 카탈로그에서 불필요한 것을 알려줍니다; "최상위 디스패치 체인"은 후보 트리거 연결을 제안합니다.
2주 연속으로 실행할 만한 것이 생성되지 않아도 여전히 신호입니다. "변화 없는 검토"를 research/lessons/에 기록하여 의식에 과적합되는 것을 방지하십시오.
agentfiles — Claude Code 가이드
이 저장소는 개인 Claude Code 스킬 모음의 진실 공급원(source of truth)입니다. 스킬은 af install을 통해 ~/.claude/skills/(사용자 수준) 또는 .claude/skills/(프로젝트 수준)에 심링크됩니다.
슬래시 명령어
스킬은 /스킬-이름 형식(예: /git-expert, /brainstorming)을 사용합니다. 이들은 수동 오버라이드입니다. 정확히 원하는 것이 무엇인지 알 때 사용하십시오. 그렇지 않으면 executor가 자동으로 라우팅을 처리합니다.
일상적인 사용에서는 이를 입력할 필요가 없습니다. using-agentfiles가 세션 시작 시 실행되고 시스템이 executor를 통해 자동 라우팅합니다.
언제 어떤 스킬을 사용할까
| 상황 | 스킬 |
|---|---|
| 새 작업 (기본값) | executor |
| 새 기능 / 컴포넌트 / 설계 | 먼저 brainstorming, 그 다음 executor |
| 버그 또는 예상치 못한 동작 | systematic-debugging |
| 익숙하지 않은 코드베이스 | codebase-explainer |
| 실행할 구현 계획 | writing-plans → subagent-driven-development |
| Python / TypeScript / Rust / Typst 작업 | python-expert / typescript-expert / rust-expert / typst-expert |
| API 설계 또는 검토 | api-architect |
| 데이터베이스 스키마 / 마이그레이션 / 쿼리 | database-expert |
| 보안 감사 | security-review |
| 성능 문제 | performance-profiling |
| 대규모 구조 변경 | refactoring-patterns |
| Docker / K8s / Terraform | infrastructure-expert |
| 의존성 업데이트 / CVE 스캔 | dependency-management |
| 로깅 / 트레이싱 / 메트릭 | observability |
| 웹 접근성 | accessibility |
| Git 작업 / 워크트리 | git-expert / git-worktree-workflow |
| GitHub PR, 이슈, Actions | github-expert / github-actions-expert |
| "X를 어떻게 사용하지?" — API 조회 | docs-agent |
| "X를 사용해야 할까?" — 트레이드오프 | research-agent |
| 참고 자료에서 질문에 답변 | test-taker |
| 메모 또는 대화형 학습 작성 | readrun |
| 병렬 다중 에이전트 작업 | manager |
| 스킬 생성 또는 편집 | writing-skills |
주요 사실
- 스킬 위치:
agentfiles/<카테고리>/.../<스킬-이름>/SKILL.md— 네 가지 카테고리:management/,planning/,coding/,research/ - 각 카테고리에는 디스패처(depatcher)가 있음:
agentfiles/<카테고리>/SKILL.md가 적절한 리프 스킬로 라우팅 af agents --tree명령어로 전체 라이브 계층 구조 확인- 지역 문서:
agentfiles/<카테고리>/REGION.md— manager가 계획 중에 이 문서를 읽음 - 설치:
./install.sh(부트스트랩), 그 다음af install(전체 설치). 새 머신은./bootstrap.sh사용. - CLI:
af <하위명령어>—tools/python/src/af/에 있는 Python CLI,uv tool로 설치
스킬 파일 형식
---
name: 스킬-이름 # 소문자, 하이픈만 사용
description: >
[트리거 조건]이 있을 때 사용. 총 1024자 미만으로 유지.
이 내용이 Claude가 스킬을 호출할지 여부를 결정할 때 읽는 내용입니다.
---
description 필드는 이 스킬을 호출하지 않고도 다른 스킬이 볼 수 있는 유일한 내용입니다. 트리거 조건이 명확하게 드러나도록 작성하십시오.
지역 문서 동기화 규칙
리프 스킬이 추가되거나 제거될 때마다 해당 카테고리의 REGION.md를 업데이트하십시오.
지역 문서(agentfiles/<카테고리>/REGION.md)는 manager가 계획 중에 읽는 스킬 카탈로그입니다. 각 항목은 ### 스킬-이름 제목 형식을 사용합니다. 실제와 다를 경우 manager가 잘못된 계획을 세울 수 있습니다.
agentfiles/를 커밋하기 전에 af check를 실행하여 모든 리프 스킬이 해당 카테고리의 REGION.md에 항목을 가지고 있는지 확인하십시오.
manifest.toml
스킬별 도구 요구사항과 설치할 bin 항목을 선언합니다. 다음 경우에 업데이트하십시오:
- 도구 요구사항이 있는 새 스킬 추가
- 새 bin 항목 추가
- 스킬의 도구 요구사항 변경
[skills.스킬-이름]
tools = ["Bash", "Read"] # Claude Code 도구 이름
mcp = ["context7"] # MCP 서버 이름 (선택 사항)
새 스킬 추가 — 체크리스트
- 카테고리 결정:
management/,planning/,coding/또는research/ - 유효한 frontmatter와 함께
agentfiles/<카테고리>/[하위-카테고리/]<스킬-이름>/SKILL.md생성 - 스킬에 도우미 스크립트가 필요한 경우
scripts/폴더 추가 -
manifest.toml의[skills.<스킬-이름>]아래에 항목 추가 - 카테고리의
agentfiles/<카테고리>/REGION.md에### 스킬-이름아래 항목 추가 -
af install실행 (다음 세션에 심링크가 적용됨)
아키텍처 참고 사항
두 가지 오케스트레이션 경로:
executor— 모든 새 작업의 기본 진입점. af context/af status로 방향을 잡고, 인라인 라우팅 결정을 내린 후 작업을 처음부터 끝까지 처리합니다. Skill 도구를 통해 전문 스킬을 인라인으로 흡수합니다. 완료를 보고하기 전에 검증이 필수입니다. 병렬 작업이 진정으로 필요할 때만 구조화된 HANDOFF CONTEXT 블록과 함께 manager로 에스컬레이션합니다.manager— 진정한 다중 에이전트 작업 전용. executor의 handoff 컨텍스트를 읽고, 계획 검토 패스(설계? git 전략? 조정?)를 실행한 후 에이전트를 디스패치하고, 에이전트가 실패할 경우 적응형 재계획을 통해 결과를 검토합니다. 조언자(design-advisor, git-advisor, coordination-advisor)는 관련 결정이 명확하지 않을 때만 인라인으로 로드됩니다.
전문가는 스킬 라이브러리이지 라우팅 대상이 아닙니다. executor가 Skill("이름")으로 인라인 로드합니다. manager가 명시적으로 병렬 도메인 작업이 필요할 때만 서브에이전트로 디스패치됩니다.
Git 전문가는 WORKTREE CONTEXT 블록을 출력합니다. 다른 스킬은 변경을 적용할 위치를 알아야 할 때 이 블록을 찾아야 합니다.
스킬은 독립적입니다. 각 스킬은 단독으로 작동합니다. 오케스트레이터는 그 위에 조정을 추가할 뿐, 독립적 사용을 대체하지 않습니다.
설치
2단계 설치:
- 부트스트랩 (
./install.sh):afCLI와agentfiles-manager스킬을 전역에 최소 설치. 스킬 선택이나 CLI 도구는 포함되지 않음. - 전체 설치 (
af install): 모든 스킬, 훅, CLI 도구 설치.--global(기본값),--local,--skill,--category,--remove,--dry-run을 지원합니다.
두 가지 모드:
- 모드 A — 전역 설치:
./install.sh && af install모든 스킬을 전역 설치. 프로젝트별 설정 없이 모든 프로젝트에서 작동. - 모드 B — manager만 설치:
./install.sh로 manager만 설치. 그런 다음 각 프로젝트에서 "이 프로젝트 설정"이라고 말하면 agentfiles-manager가 관련 스킬을 선택하여.claude/skills/에 로컬로 설치함.
복사본이 아닌 심링크를 사용합니다. 스킬 파일 변경 사항이 즉시 반영되므로 재설치가 필요 없습니다.
manifest TOML 파서는 간단한 awk/grep 파이프라인입니다. manifest.toml을 깔끔하게 유지하고 특이한 형식(값 줄의 인라인 주석, 여러 줄 배열 등)은 피하십시오.