agents 딥다이브
— 한 번 쓴 AI 작업 지침을 일곱 도구의 언어로

1프로젝트 한줄 요약

agents는 AI 코딩 도구에 전문 역할·지식·작업 절차를 추가하는 플러그인 모음과 Python 변환 도구입니다. 전문 지식은 하나의 Markdown 원본으로 관리하고, 도구마다 다른 형식과 제약은 어댑터가 처리합니다.

지원 대상으로 열거한 도구는 Claude Code, OpenAI Codex CLI, Cursor, OpenCode, Google Antigravity CLI, GitHub Copilot, Pi입니다. 저장소 자체가 이 일곱 도구를 동시에 실행하는 서비스는 아닙니다. 실제 파일 읽기·수정·모델 호출은 설치한 구성요소를 읽는 각 코딩 도구가 담당합니다.

네 가지 단위를 먼저 구분하자

위 세 구성요소는 모두 plugins/python-development/에 묶여 있습니다. plugins/python-development/agents/python-pro.md를 열면 Python 클래스 대신 YAML 머리말과 자연어 지침이 나옵니다. 그 파일을 읽는 코딩 도구가 모델에게 역할을 전달합니다.

한 플러그인의 흐름을 짧게 보면

plugins/python-development/agents/python-pro.md
        ↓ load_plugin(): 머리말과 본문 읽기
AgentSource(plugin, name, frontmatter, body)
        ↓ CodexAdapter._emit_agent(): 형식·모델·권한 변환
.codex/agents/python-development__python-pro.toml
        ↓ 해당 하네스의 발견·호출 규칙
전문 역할을 사용하는 코딩 작업

핵심 학습 대상은 “좋은 문장을 많이 모으는 법”에 그치지 않습니다. 문서를 구조화된 데이터로 읽고, 서로 다른 시스템에 배포하며, 변환 중 지켜야 할 조건을 자동 검사하는 방법을 배울 수 있습니다.

2왜 주목받는가

2026-10-23 GitHub Trending Python 주간 6위로 선정된 저장소이며, 같은 날짜 GitHub 기준 스타는 41,588개입니다. 다만 순위와 누적 스타만으로 유입 경로나 특정 기능의 효과까지 알 수는 없습니다. 아래의 주목 요인은 저장소에서 관찰되는 특징을 바탕으로 한 해석입니다.

• 바로 살펴볼 수 있는 업무 지식: Python·테스트·보안·인프라·문서화 등 다양한 작업의 출발점을 제공합니다. 빈 문서부터 역할을 설계하는 부담이 줄어듭니다.
• 도구를 바꾸어도 유지되는 원본: 지식은 plugins/에 남고, 변환 규칙은 Python 코드로 분리됩니다. 여러 도구용 사본을 사람이 계속 고치는 일을 줄입니다.
• 문서와 코드를 함께 공부하기 좋은 구조: 실제 업무 지침을 읽다가 그 지침을 배포하는 어댑터·검증기·테스트로 내려갈 수 있습니다.
• 작은 단위로 선택 가능한 구성: 전체 카탈로그 외에 특정 플러그인이나 스킬만 살펴볼 수 있습니다. 외부 플러그인 두 개는 별도 저장소의 구성요소입니다.

이 프로젝트의 장점은 실행 엔진을 새로 만드는 데보다, 이미 사용하는 코딩 도구 사이에서 업무 지식을 재사용하는 데 있습니다.

비슷해 보이는 선택지와 무엇이 다른가

LangGraph의 상태·지속 실행 설명은 공식 저장소, CrewAI의 Crews·Flows 구분은 공식 소개에 근거합니다. 이들은 설계 대상이 다르므로, 위 비교는 속도나 모델 성능의 우열을 뜻하지 않습니다.

“7개 지원”과 “7개에서 동일한 동작”은 다르다

tools/adapters/capabilities.py는 하네스별 기능을 Capability 데이터로 표현합니다. skills_native, commands_native, tool_allowlist_per_agent 같은 필드가 따로 있는 이유입니다. 명령이 어떤 도구에서는 스킬이 되고, 다른 도구에서는 프롬프트 템플릿이 됩니다.

특히 Codex의 네이티브 마켓플레이스 경로는 skills: "./skills/"를 가리킵니다. 변환된 TOML 에이전트와 명령 유래 스킬은 별도 어댑터 경로에 있습니다. Pi의 에이전트 파일은 기본 코어가 아니라 참조용 subagent 확장 또는 호환 확장을 전제로 합니다. 설치 경로까지 확인해야 실제로 얻는 구성이 분명해집니다.

3기술 스택 전체 지도

백엔드에 해당하는 부분: Python CLI와 파일 변환

핵심은 HTTP 요청을 받는 서버가 아니라 명령행 도구입니다. tools/generate.py는 표준 라이브러리 argparse로 옵션을 받고, pathlib로 파일을 다룹니다. tools/adapters/base.py는 dataclasses와 abc를 사용합니다. 평가 CLI는 Typer, 결과 데이터 검증은 Pydantic, 터미널 표시는 Rich를 사용합니다.

공통 Python 도구 환경은 plugins/plugin-eval/pyproject.toml에서 관리합니다. 프로젝트 버전은 0.1.0, 요구 Python은 >=3.12입니다. 같은 디렉토리의 .python-version은 3.14를 지정하며, 일부 CI 작업은 UV_PYTHON: "3.12"로 덮어씁니다.

이 표의 선언과 고정 버전은 모두 커밋 0874a27 기준입니다. >=는 허용 범위의 하한이고, 잠금 파일의 숫자는 해당 의존성 해석 결과입니다. hatchling.build는 패키지 빌드 백엔드로 선언되어 있지만, 그 선언에 버전 핀은 없습니다.

프론트엔드: 별도 웹앱 빌드가 없다

저장소 루트에는 package.json, Cargo.toml, pyproject.toml, go.mod, Dockerfile이 없습니다. 자체 React 화면이나 웹 서버를 실행하는 구조로 읽으면 흐름이 어긋납니다. 독자가 접하는 주된 화면은 각 하네스의 CLI·에디터와 저장소의 Markdown 문서입니다.

plugins/python-development/commands/python-scaffold.md 안에는 FastAPI·Django·Uvicorn 설정 예제가 있습니다. 이것은 사용자의 새 프로젝트를 만들기 위한 지침입니다. 그 예제에 나온 패키지가 agents 자체의 서버 의존성이라는 뜻은 아닙니다. 다른 플러그인에 등장하는 React·Kubernetes·데이터베이스도 같은 방식으로 구분해서 읽어야 합니다.

인프라·빌드: Make + uv + GitHub Actions

Makefile은 생성·검증·문서 검사·테스트 명령을 묶습니다. UV_TOOLS := uv run --project plugins/plugin-eval python이 공통 실행 환경을 선택하고, HARNESSES에는 원본 형식인 Claude Code를 제외한 여섯 대상이 들어 있습니다.

# Makefile의 핵심 변수
GENERATE := tools/generate.py
HARNESSES := codex copilot cursor opencode antigravity pi

# plugins/plugin-eval/pyproject.toml의 품질 설정
[tool.ruff]
target-version = "py312"
line-length = 100

[tool.pytest.ini_options]
testpaths = ["tests"]
asyncio_mode = "auto"

.github/workflows/validate.yml은 ubuntu-latest에서 JSON 검사, 평가 테스트, 어댑터 테스트, 재생성 후 변경 감지, 구조 검증, 실제 CLI 스모크 테스트를 정의합니다. 실제 CLI 작업에는 OpenCode 1.18.30, Pi 0.85.1, Node.js 22가 명시되어 있습니다. Antigravity 설치 단계에는 버전 핀이 없고, 어댑터 주석의 검증 대상은 agy 1.1.14입니다.

Actions 자체도 actions/checkout@34e1148…처럼 전체 커밋 SHA로 고정합니다. 다만 ubuntu-latest, Bun의 latest, 버전 없는 설치 단계까지 모두 고정된 환경은 아닙니다. “일부를 고정했다”와 “완전히 재현 가능하다”를 구분하는 좋은 사례입니다.

선택형 부속 도구: 동영상에서 디자인 단서 추출

tools/yt-design-extractor/는 패키지를 설치하지 않고 의존성만 관리하는 별도 uv 프로젝트입니다. Python 요구사항은 >=3.10이고 package = false로 설정되어 있습니다. tools/yt-design-extractor/yt-design-extractor.py의 get_transcript(), extract_frames_interval(), run_ocr_on_frames()가 자막·프레임·문자 인식을 다룹니다.

파일 수와 줄 수로 본 규모: Python보다 훨씬 큰 Markdown 원고

집계는 Git 내부 파일과 심볼릭 링크를 제외하고, 각 텍스트 파일의 빈 줄·주석도 포함한 물리적 줄 수입니다. Markdown 내부 코드 블록은 Markdown에만 셉니다. Python 중 tools/adapters/는 2,769줄, 평가 패키지 구현은 3,214줄, 두 테스트 디렉토리는 합계 8,637줄입니다. GitHub의 언어 비율을 다시 계산한 결과는 아닙니다.

이 저장소를 읽을 때는 Python이 지식을 운반하는 도구이고, Markdown이 운반할 핵심 데이터라는 관계를 먼저 잡아야 합니다.

4아키텍처 심화 분석

전체 구조에는 두 길이 있습니다. 하나는 마켓플레이스 선언이 원본 플러그인 디렉토리를 가리키는 길이고, 다른 하나는 Python 어댑터가 도구 전용 파일을 생성하는 길입니다. 모든 설치가 반드시 모든 변환 단계를 거치는 것은 아닙니다.

설계 패턴 1: 파싱과 중간 표현을 분리한다

tools/adapters/base.py의 parse_frontmatter()는 Markdown을 머리말 사전과 본문 문자열로 나눕니다. load_plugin()은 디렉토리를 탐색해 AgentSource, SkillSource, CommandSource를 만들고, 이를 PluginSource에 모읍니다.

# tools/adapters/base.py — 실제 데이터 구조 일부
@dataclass
class AgentSource:
    plugin: str
    name: str
    path: Path
    frontmatter: dict
    body: str

@dataclass
class PluginSource:
    name: str
    dir: Path
    plugin_json: dict
    agents: list[AgentSource] = field(default_factory=list)
    skills: list[SkillSource] = field(default_factory=list)
    commands: list[CommandSource] = field(default_factory=list)

어댑터는 디스크를 다시 해석하는 대신 이 공통 객체를 받습니다. 입력 규칙이 바뀌면 파싱 쪽을, 출력 형식이 바뀌면 해당 어댑터를 중심으로 수정할 수 있습니다. 한 번 읽은 원본을 공통 데이터로 정리한다는 점에서 컴파일러의 중간 표현과 비슷합니다.

주의할 점도 있습니다. 어댑터의 parse_frontmatter()는 완전한 YAML 구현이 아니라, 목록·한 단계 사전·일부 여러 줄 값을 다루는 관대한 자체 파서입니다. 문서의 모든 YAML 표현이 동일하게 해석될 것이라고 가정하면 안 됩니다. 뒤의 출력 검증 단계가 필요한 이유입니다.

설계 패턴 2: 전략 객체와 기능 행렬로 차이를 드러낸다

HarnessAdapter는 추상 메서드 emit_plugin()과 기본 구현이 비어 있는 emit_global()을 제공합니다. tools/generate.py의 get_adapter()가 대상 이름에 맞는 클래스를 지연 import합니다. 공통 실행 흐름은 유지하면서 출력 전략만 바꾸는 구조입니다.

# tools/adapters/base.py — 공통 계약의 핵심
class HarnessAdapter(ABC):
    @abstractmethod
    def emit_plugin(self, plugin: PluginSource) -> EmitResult:
        ...

# tools/adapters/capabilities.py — 커밋 기준 변환표 일부
MODEL_ALIASES = {
    "codex": {
        "opus": "gpt-5.5",
        "sonnet": "gpt-5.4-mini",
        "inherit": "gpt-5.5",
    },
}

위 표는 저장소에 들어 있는 매핑의 일부이며, 현재 모델 선택을 권장하는 표가 아닙니다. resolve_model()은 알려진 별칭을 바꾸고, 알 수 없는 별칭은 대체값과 경고를 반환합니다. 이 커밋에서 Codex의 inherit는 문자열 그대로 전달되지 않고 고정 모델로 해석됩니다. Antigravity는 inherit를 유지하고, Pi는 상속일 때 출력에서 model 필드를 생략합니다.

같은 “권한”도 도구에 따라 표현력이 다르다

빈 목록과 필드 누락은 다릅니다. AgentSource.tools 속성만 보면 둘 다 빈 목록이 될 수 있어, 어댑터는 "tools" in agent.frontmatter도 함께 확인합니다. 또한 Codex의 샌드박스 모드는 도구별 허용 목록을 완전히 보존하지 못합니다. read-only가 “도구를 하나도 쓰지 못한다”와 같은 뜻은 아닙니다.

OpenCode 변환도 만능은 아닙니다. MCP 전용처럼 원본 도구 이름이 하나도 매핑되지 않으면 빈 권한 블록을 반환하며, MCP 설정 쪽에 맡깁니다. Pi는 원본 tools: []를 빈 목록으로 전달하지 않고 읽기 도구 목록으로 바꿉니다. 원본의 의도를 얼마나 보존하는지 확인하는 일이 파일 확장자를 바꾸는 일보다 중요합니다.

설계 패턴 3: 점진적 공개와 UTF-8 예산 관리

tools/adapters/codex.py의 SKILL_BODY_CAP = 7400은 이 구현이 정한 본문 예산입니다. 기능 행렬과 검증기는 전체 스킬 파일에 대해 8 * 1024바이트를 기준으로 삼습니다. 본문 외에 머리말과 참조 안내가 붙기 때문에 본문 예산을 더 작게 둡니다.

_split_body_if_oversized()는 우선 제목 ## 경계를 활용해 본문과 초과분을 나눕니다. 어댑터는 초과분을 references/details.md에 저장하되, 스킬 원본에 같은 파일이 있으면 references/_overflow.md에 저장합니다. _split_body_fence_aware()는 백틱 코드 울타리 안의 제목을 절 구분자로 오인하지 않도록 처리합니다. 아주 긴 첫 부분은 _utf8_safe_cut()로 잘라냅니다.

# tools/adapters/codex.py — UTF-8 문자 경계로 뒤로 이동
end = cap
while end > 0 and (encoded[end] & 0xC0) == 0x80:
    end -= 1

# 문자 수와 바이트 수가 다른 이유
len("가")                 # 1
len("가".encode("utf-8")) # 3

UTF-8의 이어지는 바이트는 상위 비트가 10으로 시작합니다. 위 조건은 절단 위치가 그 중간에 놓이면 뒤로 이동합니다. 단순히 문자열 7,400자를 고르는 방식으로는 한국어·이모지가 있는 파일의 바이트 상한을 지킬 수 없습니다.

이 구조는 모델의 지식을 새로 학습시키는 과정이 아닙니다. 작업 중 읽는 문서를 어떻게 나누어 배치할지 정하는 방식입니다. 짧은 본문과 풍부한 참고 자료가 서로 연결되어 있어야 효과가 있습니다.

설계 패턴 4: 변환 계약을 기계적으로 검사한다

Codex의 에이전트·변환 스킬 이름은 <plugin>__<leaf>처럼 묶어 충돌을 줄입니다. 같은 플러그인 안의 명령과 스킬 이름이 같으면 Codex 어댑터는 명령 쪽에 __command를 붙이고, 그 이름도 스킬과 겹치면 __cmd로 우회합니다. load_plugin()은 구분자와 혼동되는 __가 포함된 플러그인 이름을 거부합니다.

HarnessAdapter.write()는 출력 경로를 resolve()한 다음 is_relative_to()로 출력 루트 안에 있는지 검사합니다. tools/generate.py는 EmitResult.written에 기록된 파일을 모으고, --all과 --prune을 함께 지정한 전체 생성에 오류가 없을 때만 prune_orphans()로 더 이상 생성되지 않는 산출물을 정리합니다.

좋은 어댑터는 파일을 만들어 내는 데서 끝나지 않고, 변환 뒤에도 무엇이 유지되어야 하는지 검사합니다.

단, 오류 발생 시 이미 쓴 파일까지 모두 되돌리는 트랜잭션 구조는 아닙니다. 생성 함수는 플러그인별 오류를 모아 계속 진행하고, 오류가 있으면 정리 단계를 건너뜁니다. “정리하지 않아 손실을 줄인다”와 “전체 생성이 원자적이다”는 구분해야 합니다.

5디렉토리 구조 해부

다음 트리는 핵심 경로를 추린 것입니다. 점(.)으로 시작하는 폴더에는 하네스별 배포 설정이 담겨 있습니다. 생성되는 디렉토리와 버전 관리되는 선언 파일을 구분해서 봅시다.

폴더 이름을 역할로 번역하기

버전 관리되는 원본과 다시 만드는 파일

.gitignore는 .codex/, .opencode/, .copilot/, .antigravity/, .pi/의 생성물을 제외합니다. 반면 작은 네이티브 설치 선언인 .agents/plugins/marketplace.json, plugins/*/.codex-plugin/plugin.json, .cursor-plugin/, .cursor/는 커밋합니다.

커밋하는 생성 파일에도 이유가 있습니다. 원본 디렉토리를 가리키는 작은 선언을 함께 배포하면 사용자가 전체 변환기를 돌리지 않고 해당 설치 경로를 이용할 수 있습니다. CI는 재생성 후 git status --porcelain이 비어 있는지 검사해, 선언이 원본과 어긋나지 않게 합니다.

보조 파일 복사 범위도 읽어야 합니다. Codex의 _emit_skill()은 기존 references/를 복사합니다. Copilot의 _emit_skill()은 숨김 파일을 제외한 스킬 지원 트리를 복사하고 심볼릭 링크를 거부합니다. assets/라는 폴더가 원본에 있다고 모든 어댑터가 똑같이 옮기는 것은 아닙니다.

6학습 포인트 (기술별)

① Python 데이터 모델: 변환용 객체와 검증용 객체

어댑터의 PluginSource 계열은 @dataclass입니다. 이미 읽은 정보를 묶어 전달하는 데 초점을 맞춥니다. 평가 쪽 plugins/plugin-eval/src/plugin_eval/models.py는 Pydantic의 BaseModel과 Field로 사용자 옵션과 결과 범위를 검사합니다.

# plugins/plugin-eval/src/plugin_eval/models.py — 동시성 옵션의 유효 범위
class EvalConfig(BaseModel):
    depth: Depth = Depth.STANDARD
    concurrency: int = Field(default=4, ge=1, le=20)
    output_format: str = "json"
    verbose: bool = False
    corpus_path: str | None = None
    judges: int = Field(default=1, ge=1, le=5)
    monte_carlo_n: int | None = None

concurrency=0이나 21은 선언된 범위 밖입니다. 내부 자료를 담는 객체와 외부 입력을 검증하는 객체가 같은 도구를 쓸 필요는 없습니다. 실습 아이디어: “파일 위치를 보관한다”와 “점수가 0~1인지 확인한다”를 각각 어느 종류의 모델에 맡길지 적어 보세요.

② 파싱·직렬화: 읽을 수 있는 문자열과 유효한 문법

parse_frontmatter()는 원본을 관대하게 읽고, yaml_scalar()는 출력할 때 특수 문자를 처리합니다. tools/adapters/codex.py의 _toml_kv()는 줄바꿈·따옴표·역슬래시를 고려합니다. 입력 파싱과 출력 이스케이프는 서로 다른 문제입니다.

예를 들어 설명이 Read: configuration이면 콜론 때문에 출력 문법을 신경 써야 합니다. tools: []는 빈 문자열과도 다릅니다. 실습 아이디어: 콜론, 쉼표, 따옴표, 여러 줄 문자열, 한국어가 들어간 예시를 각각 만들고 출력할 때 어떤 표현이 필요한지 표시해 보세요.

③ pytest: 정상 예제보다 경계 조건에서 배우는 것

tools/tests/test_adapters.py는 작은 synthetic_plugin과 격리된 output_root를 사용합니다. test_emits_agent_toml_with_remapped_model()은 출력 파일 존재만 보지 않고 TOML을 다시 파싱해 이름·모델·샌드박스를 검사합니다.

# tools/tests/test_adapters.py — 검사의 핵심 일부
parsed = tomllib.loads(content)
assert parsed["name"] == "demo__greeter"
assert parsed["model"] == "gpt-5.5"
assert parsed["sandbox_mode"] == "read-only"
assert "color" not in parsed

tools/tests/test_round_trip.py는 에이전트 수량, 전체 스킬 파일의 바이트 상한, 출력 파싱 등을 봅니다. 이런 검사는 텍스트가 조금 바뀌어도 유지해야 할 계약을 확인합니다. 실습 아이디어: “큰 파일도 만들어진다” 대신 “한글이 손상되지 않고 전체 크기가 상한 안이다”라는 검증 문장을 적어 보세요.

④ 비동기: async라는 이름보다 실제 await 순서를 본다

plugins/plugin-eval/src/plugin_eval/layers/monte_carlo.py는 asyncio.Semaphore로 동시 실행 수를 제어하며, 기본 설정은 n_runs=50, concurrency=4입니다. EvalEngine.evaluate_skill()은 깊이에 따라 심사와 반복 평가를 선택합니다.

# plugins/plugin-eval/src/plugin_eval/engine.py — 실제 실행 순서
async def _run_llm_layers(judge, mc, skill):
    judge_result = await judge.analyze_skill(skill)
    mc_result = await mc.analyze_skill(skill)
    return judge_result, mc_result

주변 주석에는 두 층을 함께 실행한다는 표현이 있지만, 위 함수에서는 첫 번째 평가를 기다린 다음 두 번째 평가를 시작합니다. 각 층 내부의 동시성과 층 사이의 동시성은 별개입니다. 실습 아이디어: 두 층의 내부 작업 수와 동시성 상한을 상자 그림으로 나누어 표현하고, 순차 실행과 병렬 실행의 차이를 설명해 보세요.

⑤ 평가 설계: 정적 점수와 실제 성공률을 구분한다

StaticAnalyzer.analyze_skill()은 머리말·오케스트레이션 문서·점진적 공개·구조·토큰 효율·생태계 일관성·하네스 이식성을 점수로 합칩니다. 정적 가중치는 각각 0.32 / 0.23 / 0.14 / 0.10 / 0.09 / 0.06 / 0.06입니다. 이름과 설명, 특정 문구, 문서 길이 같은 신호를 사용합니다.

anti_pattern_penalty()는 문제 개수에 대해 max(0.5, 1.0 - 0.05 * count)를 반환합니다. 문서 구조의 이상을 찾는 데는 유용하지만, 업무 결과물이 정확한지 직접 실행해 채점하는 식은 아닙니다. 정적 점수의 가중치와 plugins/plugin-eval/src/plugin_eval/engine.py의 최종 차원 가중치도 서로 다른 표입니다.

EvalEngine.evaluate_plugin()은 요청한 깊이에 상관없이 플러그인 전체를 정적 층으로만 평가하며, 신뢰도 표기를 Estimated로 둡니다. 스킬 단위 깊은 평가의 표시인 Certified·Certified+도 이 프로그램이 정한 이름이지 외부 인증은 아닙니다.

가장 눈여겨볼 구현: 응답 존재와 길이를 대용값으로 사용한다

# plugins/plugin-eval/src/plugin_eval/layers/monte_carlo.py — _simresult_from_messages() 일부
raw = "" if output.errored else (
    output.text.strip() or (output.result or "").strip()
)
activated = bool(raw)
quality_score = min(1.0, len(raw) / 500) if activated else 0.0

오류가 없고 응답이 있으면 활성화로 기록하며, 500자에 도달하면 길이 기반 품질값은 1이 됩니다. 500자의 틀린 설명과 500자의 정확한 설명을 이 식만으로 구별할 수 없습니다. run_simulation()은 호출 옵션에 allowed_tools=[]를 전달하고, 스킬 내용과 요청에 대한 모델 응답을 수집합니다. 실제 저장소 수정 결과와 테스트 통과 여부를 판정하는 평가 구조는 아닙니다.

점수가 높다는 말보다 먼저 확인할 것은, 그 점수가 실제로 어떤 관찰값에서 계산되었는가입니다.

plugins/plugin-eval/README.md와 evals/README.md도 LLM 심사·반복 평가를 실험적이라고 설명하고, 사람의 정답 라벨과 검증하지 않았음을 밝힙니다. 실습 아이디어: 정확한 짧은 답과 틀린 긴 답을 만들어 어떤 지표가 오판할지 표로 예측해 보세요.

⑥ 지침 작성: 역할·입력·출력을 분리한다

plugins/python-development/commands/python-scaffold.md는 요구사항을 <user_request>로 감싼 $ARGUMENTS에 두고, 호출자가 준 내용이 명령 전체의 지침을 덮어쓰는 권한은 없다고 명시합니다. 입력 데이터와 제어 지침을 구분하려는 설계입니다. 이 문장만으로 모든 지침 오염 문제가 해결되지는 않습니다.

또한 plugins/python-development/agents/python-pro.md에는 mypy·pyright 같은 일반 Python 도구가 언급되지만, 저장소의 실제 개발 규칙과 plugins/plugin-eval/pyproject.toml은 Ruff·ty를 사용합니다. 전문가 역할 문서의 폭넓은 권장 목록과 이 저장소를 개발할 때 적용하는 규칙은 다릅니다. 실습 아이디어: 대상·입력·출력·완료 조건을 각각 한 문장으로 써서 작은 코드 리뷰 스킬의 설계안을 만드세요.

7하드웨어 / 시스템 요구사항

핵심 어댑터는 텍스트 파일을 읽고 변환하는 도구입니다. 저장소에는 공통 CPU 코어 수나 RAM 최저 사양이 명시되어 있지 않습니다. GPU나 대규모 모델 가중치를 기본으로 요구하는 프로젝트로 볼 근거도 없습니다. 하네스 자체의 요구사항은 별도로 적용됩니다.

GPU가 필요해 보이는 이유와 실제 선택 사항

Makefile의 install-easyocr 설명에는 PyTorch·EasyOCR 다운로드가 약 2GB라는 안내가 있습니다. 이는 문서상 대략치이며 환경별 실제 용량은 달라집니다. 기본 플러그인 변환과 분리된 선택 경로입니다.

tools/yt-design-extractor/yt-design-extractor.py의 run_ocr_on_frames()는 EasyOCR 경로에서 easyocr.Reader(["en"], gpu=False, verbose=False)를 만듭니다. 이 경로는 CPU 사용과 영어 인식으로 설정되어 있습니다. 패키지 목록에 PyTorch가 있다고 GPU 추론 서버나 한국어 OCR 지원까지 추론하면 안 됩니다.

네트워크·계정·파일 쓰기의 범위

문서를 읽고 파일 수를 세는 일에는 모델 계정이 필요하지 않습니다. 패키지 설치는 배포 저장소, 플러그인 설치는 해당 소스, 모델 사용은 해당 제공자와의 연결이 필요합니다. Markdown 원고를 로컬에 보관한다는 사실만으로 실제 모델 작업이 모두 로컬에서 처리되지는 않습니다.

docs/plugin-eval.md의 설명 기준으로, 모델 평가 호출은 ANTHROPIC_API_KEY가 있으면 그 API 계정을 사용하고, 없으면 Claude Code 로그인 경로를 사용합니다. 정적 검사와 LLM 평가를 선택할 때 이용량이 발생하는 경계를 확인해야 합니다.

또한 make install-opencode, make install-copilot, make install-antigravity, make install-pi는 단순한 읽기 명령이 아닙니다. 산출물을 생성하고 사용자 설정 위치에 심볼릭 링크를 만드는 설치 경로입니다. 어떤 도구를 사용할지 정한 뒤 docs/harnesses.md의 범위와 구성요소 차이를 읽는 것이 순서입니다.

8직접 해볼 수 있는 실습 과제

각 과제는 저장소 원본을 읽고, 답안은 별도 연습 문서에 정리하는 방식입니다. 명령 예시는 저장소 루트를 기준으로 합니다. 설치 스크립트나 저장소의 Python 모듈을 실행하지 않아도 완료할 수 있습니다.

python3 - <<'PY'
from pathlib import Path
root = Path("plugins/python-development")
patterns = {
    "에이전트": "agents/*.md",
    "스킬": "skills/*/SKILL.md",
    "명령": "commands/*.md",
}
for label, pattern in patterns.items():
    files = sorted(root.glob(pattern))
    print(label, len(files))
    for path in files:
        print("  ", path.relative_to(root))
PY

# 읽기 전용으로 세 문서의 첫 부분 비교
sed -n '1,45p' plugins/python-development/agents/python-pro.md
sed -n '1,45p' plugins/python-development/skills/python-testing-patterns/SKILL.md
sed -n '1,45p' plugins/python-development/commands/python-scaffold.md

name = "python-development__python-pro"
description = "Python 개발 전문 역할"
model = "gpt-5.5"
sandbox_mode = "workspace-write"
developer_instructions = """
Python 개발 역할의 본문 지침이 여기에 들어갑니다.
"""

실습의 완료 기준은 명령이 끝났는지가 아니라, 입력이 출력으로 바뀔 때 지켜야 할 조건을 설명할 수 있는지입니다.

9관련 기술 심화 학습 로드맵

Python의 변수·함수·목록을 알고 있다는 전제의 학습 순서입니다. 주차는 분량을 나누는 기준이며, 실제 학습 속도에 맞춰 조정하면 됩니다. 먼저 한 플러그인을 끝까지 이해하고, 이후 다른 하네스를 비교하는 방식으로 범위를 넓힙니다.

다음 단계는 관심사에 따라 갈라진다

• Python 도구 제작이 재미있다면: 설정 파일 변환기나 문서 검사기를 작은 별도 프로젝트로 구현합니다. 입력·중간 표현·출력·검증을 분리합니다.
• 코딩 도구 확장이 재미있다면: docs/authoring.md와 docs/harnesses.md를 비교하며 하나의 지침을 두 하네스에서 어떤 의미로 읽는지 설계합니다.
• AI 평가가 재미있다면: 실제 실패 사례와 사람의 판정표를 먼저 모으는 방법을 공부합니다. 반복 횟수보다 무엇을 성공으로 정의할지가 선행합니다.
• 에이전트 앱을 만들고 싶다면: LangGraph의 상태·재개 또는 CrewAI의 Flows·Crews처럼 실행을 제어하는 개념을 이어서 공부합니다.

문서를 읽는 능력에서 시작해 변환 계약을 설계하는 능력으로, 마지막에는 결과를 검증하는 능력으로 확장해 보세요.

10핵심 키워드 사전

용어를 외웠는지보다 tools: []가 각 어댑터에서 어떻게 바뀌는지 설명할 수 있는지가 좋은 확인 문제입니다. 실제 파일 하나와 연결해 말할 수 있으면 개념이 훨씬 오래 남습니다.

11참고 링크

공식 저장소와 설계 문서

• wshobson/agents 공식 저장소 · 사용 목적과 설치 경로를 찾는 시작점
• 분석 기준 커밋의 전체 트리 · 이후 변경과 구분하여 읽을 소스
• ARCHITECTURE.md · 원본 관리와 어댑터의 설계 원칙
• docs/harnesses.md · 하네스별 설치 경로·기능·모델·권한 차이
• docs/authoring.md · 구성요소 작성과 이식성 규칙
• docs/plugins.md · 업무별 플러그인 카탈로그

핵심 소스와 검증 근거

• tools/adapters/base.py · 파서·중간 표현·공통 출력 함수
• tools/adapters/codex.py · 바이트 분할·TOML·명령의 스킬 변환
• tools/adapters/capabilities.py · 기능 행렬과 실제 모델 변환표
• tools/generate.py · 플러그인 순회·전역 생성·오류 집계·정리
• plugin-eval의 pyproject.toml · 실제 실행·개발 의존성 선언
• plugin-eval의 uv.lock · 이 커밋의 구체적인 패키지 버전
• plugins/plugin-eval/src/plugin_eval/layers/monte_carlo.py · 반복 평가가 측정하는 실제 관찰값
• evals/README.md · 점수 스냅샷과 사람의 판정에 관한 한계
• tools/tests/test_adapters.py · 어댑터가 지켜야 할 변환 계약
• .github/workflows/validate.yml · 자동 검사와 도구 버전 설정

관련 기술 공식 문서

• Agent Skills 형식 명세 · SKILL.md 머리말·지원 폴더·점진적 공개
• Python dataclasses · 데이터를 담는 클래스 작성
• Python pathlib · 경로·파일 탐색과 처리
• Pydantic 공식 문서 · 타입을 이용한 입력·결과 검증
• pytest 공식 문서 · fixture·매개변수화·예외 검사
• uv 공식 문서 · 프로젝트·의존성·잠금 파일 관리
• Ruff 공식 문서 · 린트·포맷 설정
• LangGraph 공식 저장소 · 상태를 유지하는 에이전트 실행 구조
• CrewAI 공식 소개 · Flows와 Crews의 역할 구분

Agent Skills 명세는 메타데이터·본문·지원 자료를 필요에 따라 읽는 구조를 설명합니다. 다만 표준의 일반 권장사항과 이 저장소의 하네스별 예산은 구분해야 합니다. 예를 들어 Codex 어댑터의 7400은 이 구현의 본문 예산이며, 모든 스킬 표준에 공통인 숫자가 아닙니다.

현재 상태 (2026-10-23 GitHub 기준)

최근 push 시각과 분석 기준 커밋의 시각은 서로 다른 기준이므로 일치하지 않을 수 있습니다. 또한 커밋 하나의 정보만으로 저장소 전체의 누적 커밋 수나 과거 성장률을 단정할 수 없습니다. 주간 순위는 해당 날짜의 기록이며, 이후의 Trending 화면과 다를 수 있습니다.