레퍼런스
헬퍼
프런트매터 계약과 배포 격리 프로토콜을 갖춘, 리서치·감사·품질·오케스트레이션을 위한 영속적 헬퍼 에이전트입니다.
영속적 헬퍼는 표준 헬퍼 디렉터리 아래에 <name>.md 접미사를 가진 플랫
파일로 존재합니다. 표준 경로는 다음과 같습니다.
src/apothem/agents/각 헬퍼는 리서치, 감사, 품질, 리팩터링, 스캐폴딩 같은 특정 업무에 집중한 역할이며, 자체 도구 제한과 시스템 프롬프트를 가집니다.
아래의 표와 경로 목록은 헬퍼 중 네 개를 보여 줍니다. 이 페이지 끝의 생성된 인벤토리는 모든 헬퍼 정의를 나열합니다.
| 헬퍼 | 파일 | 패턴 | 모델 정책 |
|---|---|---|---|
| Codebase Explorer | 아래 매니페스트 경로 참조 | 리서치 | 호스트 선택 |
| Convention Auditor | 아래 매니페스트 경로 참조 | 감사 | 호스트 선택 |
| Quality Gate | 아래 매니페스트 경로 참조 | 품질 | 호스트 선택 |
| Memory Auditor | 아래 매니페스트 경로 참조 | 감사 | 호스트 선택 |
표준 매니페스트 경로:
src/apothem/agents/codebase-explorer.md
src/apothem/agents/convention-auditor.md
src/apothem/agents/quality-gate.md
src/apothem/agents/memory-auditor.md프런트매터 계약
---
name: <agent name>
version: <semver>
updated: <YYYY-MM-DD>
description: <one-line role>
tools: <comma-separated tool list>
disallowedTools: <comma-separated deny list>
maxTurns: <integer>
---tools는 선택 사항입니다. 이를 생략한 헬퍼는 연결된 MCP 도구를 포함해 세션이
가진 모든 도구를 상속하며, disallowedTools가 그 제한을 담당합니다. 제공되는
열네 개의 헬퍼는 모두 tools를 나열합니다.
연결된 MCP 서버
tools를 나열한 헬퍼는 나열한 것만 호출할 수 있습니다. Claude Code는 항목이
mcp__<server>__*처럼 서버를 지명할 때만 MCP 도구를 그 목록에 허용합니다. 단독
mcp__*는 disallowedTools 항목으로만 문서화되어 있으며 다른 곳에는 문서화되어
있지 않습니다. 서버 이름은 서버를 연결하는 사람의 것이므로, 제공되는 헬퍼는 그
이름을 지명할 수 없습니다.
citation-auditor와 research-scout는 학술 소스를 조회합니다. 각각
tools: Read, Glob, Grep, WebSearch, WebFetch와 함께 제공되며, 파일을 쓰거나,
명령을 실행하거나, 다른 헬퍼를 시작하거나, 게시하는 도구를 거부합니다: Write,
Edit, MultiEdit, NotebookEdit, Bash, PowerShell, Monitor, Agent,
Artifact, 그리고 작업 목록 도구입니다. 프로필 설정이 없으면 둘 다 MCP 도구에
닿지 않으며, 둘 다 웹 검색과 웹 가져오기로 소스를 조회합니다.
둘 중 하나에 연결된 학술 인덱스를 주려면, 에이전트 이름을 서버 이름에 매핑하는
프로필의 agent_mcp_servers 키에 서버를 지명하세요. 그러면 Claude Code 엔진
설치(apothem install)가 그 에이전트의 tools 줄에 지명된 서버마다
mcp__<server>__* 항목 하나를 덧붙이며, 다른 에이전트는 변경하지 않습니다.
Gemini CLI 설치도 문자, 숫자, -로 된 서버 이름에 대해 에이전트의 tools 허용
목록에 서버마다 mcp_<server>_* 항목 하나를 넣어 같은 일을 합니다. 두 경우 모두
에이전트 자체의 disallowedTools가 지명한 서버는 계속 거부됩니다. 이 항목은 쓰기를
하는 도구까지 포함해 그 서버의 모든 도구를 허용하므로, 조회 용도로 신뢰하는 서버만
지명하세요. 헬퍼의 지침은 헬퍼를 검색, 조회, 읽기, 검증, 해석 호출로 제한하지만,
하니스는 tools 줄이 나열한 이름만 강제합니다. 존재하지 않는 에이전트나 명시적
tools 줄이 없는 에이전트에 대한 이름은 보고되고 건너뜁니다.
Claude Code와 Gemini CLI 외의 하니스는 이 키를 무시합니다. Claude Code 플러그인
트리는 프로필 없이 조립되어 평범한 목록을 유지하므로, 플러그인 사용자는 대신
~/.claude/agents/ 아래에 사용자 수준 에이전트를 정의합니다. 프로필 구문, 서버
이름 규칙, 그 우회 방법은
헬퍼에 MCP 서버 접근 권한 부여하기에
있습니다.
하니스별 변환
disallowedTools를 적용한 뒤에도 tools 부여에 파일 편집 도구(Write,
Edit, MultiEdit, NotebookEdit)가 하나도 포함되지 않은 헬퍼는 읽기
전용입니다. tools 부여가 없는 헬퍼는 disallowedTools가 적어도 Write와
Edit를 거부할 때 읽기 전용입니다. 헬퍼를 변환하는 각 하니스는 그 제한을
네이티브로 강제하거나, 헬퍼의 지침에 명시하거나, 읽기 전용 레이블을 제거합니다.
| 하니스 | 도구 제한 | 턴 제한 | 모델과 노력 수준 |
|---|---|---|---|
| Claude Code | 작성된 그대로의 tools / disallowedTools, 그리고 프로필의 agent_mcp_servers 키가 나열된 tools 줄에 추가하는 mcp__<server>__* 항목. tools가 없으면 MCP를 포함한 모든 도구가 상속됨 | maxTurns | 상속(설정하지 않음) |
| Codex | 방출되는 것 없음. 헬퍼의 지침이 이를 명시하며, 쓰기는 부모 세션의 샌드박스가 통제함 | 사용할 수 없음 | 상속(설정하지 않음) |
| Gemini CLI | Gemini 도구 이름으로 된 tools 허용 목록, 그리고 프로필의 agent_mcp_servers 키가 나열된 명시적 목록에 추가하는 mcp_<server>_* 항목. tools가 없으면 거부 항목이 함축하는 허용 목록에 mcp_*를 더함 | max_turns | 상속(설정하지 않음) |
| Qwen Code | Qwen 도구 이름으로 된 tools / disallowedTools. tools가 없으면 목록을 방출하지 않으므로 MCP 도구가 상속되고 거부 항목이 적용됨 | 매핑되지 않음 | model: inherit |
| OpenCode | permission(도구별 allow / deny). MCP 도구는 제한되지 않음 | 매핑되지 않음 | 상속(설정하지 않음) |
| Antigravity | 방출되는 것 없음. 설명에서 "read-only"가 빠짐 | 사용할 수 없음 | 상속(설정하지 않음) |
| CodeBuddy | 쉼표로 구분된 문자열로 된 tools / disallowedTools, CodeBuddy가 문서화한 도구 이름으로 한정. MCP 항목 없음 | maxTurns | 상속(설정하지 않음) |
| Trae | 쉼표로 구분된 문자열로 된 tools / disallowedTools, Trae가 문서화한 도구 이름으로 한정. MCP 항목 없음 | 사용할 수 없음 | 상속(설정하지 않음) |
| GitHub Copilot | Copilot에는 거부 키가 없으므로 거부 항목을 반영한 Copilot 별칭(read, search, edit, execute, web, agent, todo)의 tools 허용 목록. 거부된 도구를 포함하는 별칭은 제외됨. MCP 항목 없음 | 사용할 수 없음 | 상속(설정하지 않음) |
| Cursor | 도구 목록 없음(Cursor에는 도구 목록이 없음). Bash가 없는 다섯 개의 읽기 전용 헬퍼에는 readonly: true, 나머지 읽기 전용 헬퍼는 "read-only" 레이블이 빠짐 | 사용할 수 없음 | 상속(설정하지 않음) |
| Kimi Code | Kimi Code 도구 이름 목록으로 된 tools / disallowedTools(WebFetch는 FetchURL, TodoWrite는 TodoList가 되고, Kimi Code에 해당 도구가 없는 이름은 제외됨). MCP 항목 없음 | 사용할 수 없음 | 상속(설정하지 않음) |
| Kiro | 작성되는 제한이 이 목록뿐이므로 거부 항목을 반영한 Kiro 도구 범주(read, write, shell, web, subagent)의 tools 허용 목록. 거부된 도구를 포함하는 범주는 제외됨. MCP 항목 없음 | 사용할 수 없음 | 상속(설정하지 않음) |
| Windsurf | Devin에는 거부 키가 없으므로 거부 항목을 반영한 Devin 도구 이름(read, edit, grep, glob, exec, write)의 allowed-tools 허용 목록. 웹 도구가 필요한 세 헬퍼는 설치되지 않음. MCP 항목 없음 | 사용할 수 없음 | Devin의 기본 서브에이전트 모델(설정하지 않음) |
Hermes와 Open-Claw는 헬퍼 파일을 네이티브 헬퍼가 아니라 지원 자료로 받습니다.
오케스트레이션
헬퍼 배포, 병렬 실행 프로토콜, 반환 계약 강제, 격리 규율은 오케스트레이션 규칙에 있습니다. 작업자별 디스패치 트리는 오케스트레이션 패턴 규칙의 §Decision Tree에 있습니다. 표준 경로:
src/apothem/rules/agent-orchestration.md
src/apothem/rules/agent-orchestration-patterns.md생성된 에이전트 인벤토리
| Name | Description | Source |
|---|---|---|
README | Persistent agent definitions — the reusable sub-agent specifications the harness materializes whenever the orchestrator deploys a research, audit, or quality team. Each agent is a | src/apothem/agents/README.md |
citation-auditor | Read-only citation audit — checks that each reference in a bibliography or cited passage exists, matches its record, and that the opened source states what the text attributes to it. Use when a draft cites sources: 'check my references', 'are these DOIs real', 'does this paper say what I cite it for'. Finding new sources routes to research-scout; a free-standing claim routes to fact-checker. | src/apothem/agents/citation-auditor.md |
codebase-explorer | Read-only codebase exploration — exhaustively find every instance of a pattern, trace call/import dependencies, discover host conventions, map architecture and layering. Use when the query is 'where is X used', 'find all callers of Y', 'what convention does this repo follow for Z', 'map the module structure', or 'trace what depends on this file' — never for edits or design, and never for review verdicts (architecture-review, code-audit). Works through Grep / Glob / Read plus read-only Bash and returns evidence-cited findings (path + line + snippet) exhaustive within the declared scope; reports gaps rather than guessing. | src/apothem/agents/codebase-explorer.md |
convention-auditor | Read-only conventions auditor: verify naming (kebab-case files, snake_case Python, frontmatter keys), cross-reference resolution (dead rule/skill/agent paths, broken anchors, half-edge bindings), formatting standards (SPDX header presence, frontmatter contract), and ecosystem coherence (orphan artifacts, sibling-convention drift, registry gaps). Dispatch when a change touches multiple rules/skills/agents/commands and you need a binary PASS/FINDING verdict per instance with file+line+expected+actual evidence — e.g. 'audit naming across the harness adapters', 'check every new rule resolves its Bindings cross-refs', 'verify the skills cohort matches the kebab-case + SKILL.md convention'. Read-only: never fixes, never runs shell. A whole-tree sweep, or any fix, is the ecosystem-audit skill. Conventions are owned upstream and verified against, never re-derived; every finding cites severity + evidence. | src/apothem/agents/convention-auditor.md |
dependency-auditor | Read-only dependency-tree risk audit — flags unpinned, stale, duplicate, and known-vulnerable dependencies with manifest/lockfile evidence. Dispatch within a dependency audit, before a release cut, or after adding a dependency; one named CVE or advisory routes to the vuln-triage skill, and a signing or provenance review to the supply-chain-audit command. Detects the ecosystem via host-discovery: npm (package.json + package-lock/yarn/pnpm), pip (pyproject/requirements + lock), cargo (Cargo.toml + Cargo.lock), go (go.mod + go.sum). Runs npm audit / pip-audit / cargo audit / govulncheck and returns a risk-ranked table (known-vulnerable → unpinned → duplicate → stale) with per-row evidence; never widens a pin or escalates a scope — gaps surface as inquiry. | src/apothem/agents/dependency-auditor.md |
design-critic | Read-only UI critique. Use for a design review, a usability or accessibility check, or 'what is wrong with this screen' before a UI ships. A WCAG sweep across a whole web surface routes to the a11y-audit command; a CLI or install-flow review to ux-review. Reviews code, screenshots, or a running page and returns fixes ranked by user impact, from a scored heuristic review and separately measured evidence. Opens with a degraded notice when measurement tooling is missing; never guesses a measurement. | src/apothem/agents/design-critic.md |
fact-checker | Read-only adversarial claim verification — decompose input into atomic claims, seek ≥2 independent sources, attempt refutation, assign cited verdicts (supported / refuted / unverifiable) with quoted evidence and confidence. Use when a claim needs proof before it ships: a benchmark or statistic in docs/copy, a 'X is faster/safer than Y' assertion, a citation that names an RFC or spec, a release note, or any factual claim a reviewer would challenge. Routes external claims through WebSearch / WebFetch and repository claims through Read / Glob / Grep; defaults to refuted-or-unverifiable when evidence is insufficient, never a charitable supported. | src/apothem/agents/fact-checker.md |
mcp-builder | Scaffold a Model Context Protocol (MCP) server skeleton from a tool/resource contract — contract-first, well-typed tools, minimal surface. Use when: 'build an MCP server for <API>', 'scaffold MCP tools from this spec', 'wire FastMCP/TypeScript-SDK tool definitions', 'add a tool that exposes <resource> over MCP'. Detection: tool names + argument shapes + return types + resource URIs are stated or derivable. Selects the SDK via host-discovery (FastMCP for Python, the TypeScript SDK for Node), emits one typed tool definition per contract entry plus a list-tools smoke test, and scaffolds nothing speculative. Not for: tuning, securing, or load-testing an existing server (those surface as adjacent gaps). | src/apothem/agents/mcp-builder.md |
memory-auditor | Read-only memory-file auditor: cross-reference every claim in the harness memory tier (MEMORY.md index + topic files under <harness-root>/projects/{hash}/memory/ and <harness-root>/memory/) against actual filesystem state — file/line/rule counts (glob and count), referenced paths (do they exist?), rule scope labels (match pathFilter frontmatter?), dates (against frontmatter updated: or mtime, never the system clock), and cross-reference matrices. Dispatch when MEMORY.md or a topic file may have drifted from reality and you need a per-claim PASS/FAIL verdict with contradicting evidence — e.g. 'audit MEMORY.md after the rules cohort was renamed', 'verify the memory index counts match the current ecosystem', 'check the debugging topic file for stale references to deleted artifacts'. Existence + name match only; never re-audit an artifact's internal correctness (convention-auditor's scope). Read-only: never writes, never fixes. | src/apothem/agents/memory-auditor.md |
prompt-evaluator | Read-only rubric scoring of a prompt's output set — score each output against each named criterion (PASS/FAIL with cited evidence), aggregate per-criterion pass-rate, flag regressions against a baseline, and name recurring failure modes. Use when prompt or model outputs need a reproducible verdict before they ship: comparing a reprompted variant against the prior version, gating a system-prompt change, judging an LLM-as-judge eval set, scoring few-shot outputs against acceptance criteria, or proving a quality claim a reviewer would challenge. Scores outputs that already exist: building the dataset, scorer or runner routes to the eval-harness skill, and a full campaign to the eval command. Requires an explicit rubric — an absent or underspecified rubric blocks scoring and routes as inquiry; never invents a criterion or threshold, never scores charitably. | src/apothem/agents/prompt-evaluator.md |
quality-gate | Read-only quality-gate runner — discovers the host's lint / type-check / test / security / build commands, runs them in the correct order (build → type-check → tests+lint+security in parallel), and returns a per-gate PASS/FAIL verdict with file+line+error evidence. Reports, never fixes. Dispatch as a Quality team before a release cut, after a multi-file change, or to confirm a fix is green — e.g. 'run the full quality matrix and tell me what fails', 'gate this branch before I push', 'is the test suite green and the types clean?'. Runs the whole matrix; tests alone route to test-runner. Detects tooling via host-discovery (ruff/eslint/markdownlint, mypy/tsc/pyright, pytest/jest/cargo test/go test, bandit/npm audit/gitleaks); never assumes a stack. | src/apothem/agents/quality-gate.md |
refactor-surgeon | Scoped, behavior-preserving refactor of a named target — extract the behavioral contract, re-derive clean-room (never edit in place), name the one deficiency removed, verify regression via the host's own tests. Dispatch as a delegated team member on a single named target with a clear refactor intent; a user-driven interactive extraction is the refactor-extract skill — e.g. 'consolidate the duplicated validation in the CLI's install module', 'untangle the nested conditionals in the config renderer without changing output', 'rename the god-object methods in the adapter class to reveal intent'. Touches only the named target; adjacent gaps surface as findings, never as edits. Behavior, contracts, and side effects are identical before and after; a behavior change is a defect. | src/apothem/agents/refactor-surgeon.md |
research-scout | Read-only source discovery and ranking — decompose a research question into facets, fan out parallel web queries, rank candidates by authority, recency, and relevance, and return a deduplicated ranked source list. Use when a question needs sources before it can be answered: 'find the authoritative spec/RFC for X', 'what are the primary sources on Y', 'gather current references for a docs/copy claim', 'survey the landscape before a deep dive'. Fans external facets through any scholarly index server the operator has granted it, WebSearch, and WebFetch, and any in-repo corpus through Read / Glob / Grep. Also looks up papers and preprints by DOI, arXiv id, or topic ('find the paper behind this DOI'), and scouts existing open-source projects before anything new is built ('is there already a library for this', 'adopt or fork'). Discovery and ranking only — never fabricates a URL, never synthesizes; a written cited report routes to the multi-source-research skill, claim verification to fact-checker, and combining given documents to source-synthesis. | src/apothem/agents/research-scout.md |
security-scanner | Read-only secret, SAST-pattern, and config-risk sweep — a coarse first-pass that surfaces candidates fast and routes deep scanning to the host's CI scanners. Dispatch inside a security audit, after touching auth/crypto/IO surfaces, or when a secret may have been committed; a full repository security audit routes to the security-audit command. Greps for credential literals (key/token/password/private-key/certificate, committed .env values), injection surfaces (shell=True on untrusted input, string-formatted SQL, command interpolation), unsafe-eval (eval/exec/Invoke-Expression), unsafe deserialization (pickle.loads, yaml.load without SafeLoader), and config risk (over-broad CI permissions:, unpinned Actions uses:, network egress). Routes known-vulnerable dependencies to the dependency-auditor agent, CVE/advisory triage to the vuln-triage skill, and leaked-credential rotation to the secret-rotation skill. | src/apothem/agents/security-scanner.md |
test-runner | Read-only test-suite runner — discovers the host's test command, runs it, and triages every failure by root cause with test+file+line+assertion evidence. Reports, never fixes. Dispatch as a Research/Quality team member after a code change, before a release cut, or to confirm a fix is green — e.g. 'run the tests and tell me what's failing and why', 'is the suite green on this branch?', 'triage the failures in the auth module'. Tests only: lint, type and security gates route to quality-gate. Detects the runner via host-discovery (pytest/jest/cargo test/go test/Makefile target from the manifest + CI config); never assumes pytest. | src/apothem/agents/test-runner.md |