Thulr/agent-skill-kit

Agent DX

AI 에이전트가 개발자인 표면의 개발자 경험 — 에이전트가 함께 빌드하거나 작동하기 위해 소비하는 SDK, 도구, 구조화된 출력, 오류 엔벨로프 또는 텔레메트리. 출처는 skill.json에 있으며; 이 파일은 런타임 라우팅 전용입니다.

결과물: change-plan.md (DO), audit-report.md 와 findings-ledger + workflow-state (추적 시, REVIEW), 또는 design-doc.md / refactor-runbook.md / explanation.md (DESIGN).

핵심 원칙

에이전트는 표면을 단독으로, 기계 속도로, 의지할 툴팁 없이 소비합니다. 따라서 SDK, 도구, 오류 또는 스팬에 대한 기준은 확률적 소비자가 이를 구문 분석하고, 복구하며, 손상되지 않을 수 있는지 여부입니다: 산문보다는 타입화된 계약; 복구는 설계 시 포함되어야 하며, 희망에 맡겨서는 안 됨; 신뢰 경계는 기본적으로 닫혀 있어야 합니다. 이는 dx-audit / dx-design이 소유하는 HTTP-클라이언트 층 위에 위치하며, 이를 대체하지 않습니다.

활성화

• 직접 호출 ("use agent-dx", "review our MCP tool surface", "start"): references/intent-router.csv를 로드하고, 의도 메뉴를 표시하며, 모드를 제공합니다. 대기합니다. 파일 검사, 네트워크 호출 또는 쓰기 작업 없음.
• 구체적 호출 (의도와 표면을 추론할 수 있는 경우): 3단계로 건너뜁니다.
• 모호한 범위: 후보 의도 또는 표면을 명명하는 하나의 차단 질문을 합니다. 먼저 비공개 시스템을 검사하지 않습니다.

워크플로

1. 의도 선택. references/intent-router.csv를 로드하고 do, review, 또는 design에 매칭합니다. 모호함 → 한 번 질문.
2. 표면 선택. references/intents/<intent>.csv를 로드하고 sdk-design, tools-and-mcp, structured-output, errors-and-retry, sdk-telemetry 중 하나 이상에 매칭하거나 REVIEW 팬-아웃을 위해 all에 매칭합니다. 모호함 → 메뉴와 함께 한 번 질문.
3. 근거 컨텍스트 로드. 선택한 행의 playbook과 해당 core_refs만 로드합니다. 다른 플레이북은 로드하지 마십시오 (review/all 행은 플레이북이 없음 — 각 표면 에이전트는 자체 플레이북을 로드합니다. 6단계 참조).
4. 대상 페르소나 식별 references/core/personas.md에서.
5. 그런 다음 프로젝트 규모에 맞게 보정 (REVIEW / DESIGN) references/calibration.md에 따라: Load-bearing 미만은 범위를 좁히고, 동일 메커니즘의 갭을 하나의 시스템적 발견으로 통합하며, 지금과 **나중에(성장함에 따라)**를 분할합니다. 등급은 심각도가 아닌 결과물에 영향을 줍니다.
6. 렌즈를 병렬로 디스패치 (허용 시 REVIEW 기본값): all의 경우 표면당 하나의 에이전트; 그렇지 않으면 아래 세 가지 렌즈. 위임 프리미티브가 없으면 순차적으로 폴백.
7. 플레이북 적용. 의도에 태그된 휴리스틱을 사용합니다. REVIEW의 경우 각 표면에 0–10점을 매깁니다(references/core/score-rubric.md); 렌즈 결과를 종합하고, 불일치 사항은 열린 질문으로 유지합니다. 심각도와 안정적인 AGENT-DX-<표면>-NNN ID(references/core/severity-rubric.md)를 적용합니다: AGENT-DX-SDK, AGENT-DX-TOOL, AGENT-DX-OUT, AGENT-DX-ERR, AGENT-DX-TEL.
8. 출력. DO → templates/change-plan.md. REVIEW → templates/audit-report.md. DESIGN → templates/design-doc.md (형태), templates/refactor-runbook.md (강화 순서), 또는 templates/explanation.md (원칙 설명).
9. 추적 상태 생성, 재개 또는 종료 (REVIEW). 7개 이상의 발견 사항, 심각도 3–4 또는 저장/추적/종료 요청이 있는 감사의 경우 references/trackable-findings.md를 로드합니다. 요청이 기존 원장(ledger), 워크플로 상태, PR 또는 AGENT-DX-* ID를 명명하는 경우 먼저 저장된 상태를 읽습니다. 각 검증 규칙이 통과된 후에만 상태를 업데이트합니다. 그렇지 않으면 docs/audits/agent-dx-findings-ledger-<YYYY-MM-DD>-<scope-slug>.md에 원장을, docs/audits/agent-dx-workflow-state-<YYYY-MM-DD>-<scope-slug>.json에 워크플로 상태를 씁니다 (docs/audits/에 쓸 수 없는 경우 audit-artifacts/agent-dx-...로 폴백). 두 경로를 모두 보고합니다. 로드맵, 이슈 및 추적 외 편집은 옵트인으로 유지합니다.

모드

Guided Draft (기본값), Autopilot, Grill Me — references/modes.md 참조. 직접 호출 시 제공하고, 구체적 호출 시 Guided Draft를 기본값으로 합니다.

출력 요구 사항

모든 출력은 의도, 표면, 페르소나, 적용된 플레이북 및 skill.json의 근거 소스를 명명합니다. REVIEW는 발견 사항별로 심각도와 검증 및 프로젝트 등급을 추가합니다. 의도적으로 추가하지 않는 에이전트 소비성 보장(YAGNI)도 추가하는 보장만이 아니라 명명하십시오.

하위 에이전트 디스패치

위임이 허용될 때 REVIEW의 기본값입니다. 작거나 비밀이 있는 작업은 건너뜁니다. 세 가지 렌즈를 병렬로 생성합니다 — 계약-및-스키마 (코드의 타입화된 스키마, 안정적인 오류 엔벨로프, 검증된 출력), 에이전트-복구 (중지+확인, 재시도 형태의 오류, 의미적 재시도, 제한된 루프), 신뢰-및-격리 (도구 메타데이터 주입, 가드레일 체크포인트, 자격 증명 벽, 콘텐츠 교정) — references/subagent-dispatch.md에 따라, 그런 다음 종합하여 심각도 순으로 정렬합니다.

참조 맵

• references/intent-router.csv + references/intents/<intent>.csv — 두 라우팅 계층.
• references/playbooks/<surface>.md — sdk-design, tools-and-mcp, structured-output, errors-and-retry, sdk-telemetry.
• references/subagent-dispatch.md — 세 가지 렌즈 프롬프트 및 종합.
• references/core/{severity-rubric,score-rubric,personas,glossary}.md — 척도, 대상, 용어.
• references/{calibration,trackable-findings,modes}.md — 공유 (심볼릭 링크).
• templates/*.md — change-plan, audit-report, design-doc, refactor-runbook, explanation 및 공유 추적 아티팩트.
• evals/, skill.json — 게이트 및 출처.