justinramos101/agent-skill-kit

Agent DX

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

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

핵심 원칙

에이전트는 단독으로, 기계 속도로, 툴팁에 의존하지 않고 표면을 소비합니다. 따라서 모든 SDK, 도구, 오류, 또는 스팬(Span)의 기준은 확률적 소비자가 이를 구문 분석하고, 복구하며, 피해를 입지 않을 수 있는지 여부입니다: 산문(Prose) 대신 형식화된 계약; 막연한 기대가 아닌 설계된 복구; 기본적으로 닫힌 신뢰 경계. 이는 dx-audit / dx-design이 소유하는 HTTP-클라이언트 층 위에 위치하며, 결코 대체하지 않습니다.

활성화

• 단순 호출 ("use agent-dx", "start"): 간결한 메뉴 표시: 모드 선택 (가이드 / 자동 / 질문?) 및 라우터에서 번호가 매겨진 의도 표시. 대기. 파일 검사, 네트워크 호출, 쓰기 작업 없음.
• 구체적 호출(의도 및 표면을 유추할 수 있는 경우): 3단계로 건너뜁니다.
• 모호한 호출: 한 가지 질문 — 예를 들어 "SDK, 도구 스키마, 구조화된 출력 봉투, 또는 텔레메트리 표면을 감사하시겠습니까?" 또는 "이것은 계약/복구 검토입니까, 아니면 신뢰 경계 감사입니까?"

워크플로

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) 미만이면 범위 좁히고, 동일 메커니즘의 갭을 하나의 시스템적 발견으로 통합하며, 지금(Now) 과 나중(성장함에 따라) 을 분리. 계층(Tier)은 심각도가 아닌 방출(Emission)에 영향을 줌.
6. 렌즈를 병렬로 디스패치 (허용 시 REVIEW 기본값): all의 경우 표면당 하나의 에이전트; 그렇지 않으면 아래 세 가지 렌즈. 위임 프리미티브가 없으면 순차적 폴백.
7. 플레이북 적용. 의도에 태그된 휴리스틱 사용. REVIEW의 경우 각 표면을 0–10으로 채점 (references/core/score-rubric.md); 렌즈 발견 사항 종합, 불일치는 열린 질문으로 보존. 심각도 및 안정적인 AGENT-DX-<surface>-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-...로 폴백). 두 경로 모두 보고; 로드맵, 이슈 및 비추적 편집은 옵트인 유지.

잘못된 방향? 사용자가 의도한 바가 아니라면 1단계(의도 선택)로 돌아가십시오 — 잘못된 방향으로 패치하지 마십시오. 수정된 이해를 다시 설명하고 재계획하십시오.

모드

가이드 초안(기본값), 자동 조종, 질문 — references/modes.md 참조. 단순 호출 시 제공; 구체적 호출 시 가이드 초안 기본값.

출력 요구사항

모든 출력에는 의도, 표면, 페르소나, 적용된 플레이북, 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/*.md — 심각도, 점수, 페르소나, 용어집.
• references/{calibration,trackable-findings,modes}.md — 공유 (심볼릭 링크).
• templates/*.md — change-plan, audit-report, design-doc, refactor-runbook, explanation, 및 공유 추적 아티팩트.
• evals/, skill.json — 게이트 및 출처.