AGENT SKILL

debug

Investigate a failure whose cause is not evident from the error itself - flaky or intermittent failures, failures that only happen in CI or one environment, or errors with several plausible causes across files - by reproducing, isolating, fixing and verifying. Skip it when the message already shows the fix (a missing variable, a typo, a wrong import); just fix that directly.

License 许可
Apache-2.0
最近更新
2026-11-14
Stars
★ 1.6k
Forks
491

01 前言 Front Matter

name
debug
description
Investigate a failure whose cause is not evident from the error itself - flaky or intermittent failures, failures that only happen in CI or one environment, or errors with several plausible causes across files - by reproducing, isolating, fixing and verifying. Skip it when the message already shows the fix (a missing variable, a typo, a wrong import); just fix that directly.

02 资源文件 2

03 SKILL.md 正文

디버깅 실행

4-Phase Debugging Reproduce → Isolate → Fix → Verify

호출되면 바로 파이프라인을 시작한다. 단계가 바뀔 때 한 줄로 진행을 알린다.

에러 정보: $ARGUMENTS

원인이 여러 개인 실패는 references/hypothesis-evidence.md를 읽고 가설별 구분 실험을 기록한다. 코드 구조/정의/참조가 필요하면 사용 가능한 호스트 도구 또는 code-intel을 선택한다.


파이프라인 구조

Phase 1 Reproduce → Phase 2 Isolate → Phase 3 Fix → (수정 반영) → Phase 4 Verify
└─ fix-bugs (진단 전용) ─┘            fix-bugs (격리)               verify-code

위임 수단이 없는 하네스 — 강등 경로

아래 subagent_type: 블록은 운송 수단일 뿐이고, 불변식은 블록의 prompt: 계약(검사 항목·출력 형식·완료 선언)이다. 쓸 수 있는 수단을 호스트에 확인하고 위에서부터 한 칸씩 내려간다: ① 네이티브 서브에이전트(블록 그대로) → ② 호스트의 다른 격리 위임 수단(에이전트 정의 본문 <플러그인 루트>/agents/<이름>.md 를 요약 없이 넘기고 뒤에 prompt: 를 붙인다 — 플러그인 루트 탐색은 skills/plan-task/references/task-tools-fallback.md §A. 회신 요약이 아니라 계약 산출물로 판정한다) → ③ 이 세션에서 같은 계약을 직접 수행. 수단이 없다고 단계를 건너뛰거나 하지 않은 위임을 했다고 보고하지 않는다. ③은 격리가 없다 — 판정을 서술이 아니라 재현 명령의 실제 출력으로 하고, 기각한 대안 원인을 최소 1개 적는다.

Phase 1-2: 재현 및 격리 (Reproduce + Isolate)

진단 전용 호출은 격리 이득이 없다. 읽기·재현 명령만 하고 파일을 고치지 않으므로 (rules/parallel-worktree.md — 읽기 전용 작업자에 격리를 걸지 않는다) 프롬프트에 "수정 금지"를 명시한다. fix-bugs 정의에 격리가 걸려 있어 호출 단위로 끌 수 없는 호스트면 그것은 감수한다 — 이 단계에서 생긴 수정이 있으면 반영하지 않고 버린다.

Task tool 사용:
subagent_type: fix-bugs
model: opus
prompt: |
  (진단 전용 — 이 단계에서는 수정하지 말고 원인·재현 명령·근거만 보고)
  다음 에러를 진단해주세요:
  $ARGUMENTS

  ### Phase 1: Reproduce (재현)
  - 에러를 재현하는 최소 단계 식별
  - 재현 조건 및 환경 확인
  - 에러 발생 빈도 (항상/간헐적)

  ### Phase 2: Isolate (격리)
  - 에러 유형 (문법/타입/런타임/빌드/외부API)
  - 파일 위치 및 라인 번호
  - 스택 트레이스 분석
  - 루트 원인 파악
  - 영향 범위 (단일 함수/모듈/시스템 전체)

  ### 수정 방안 제안
  - 옵션 A: [빠른 수정]
  - 옵션 B: [근본 해결]

Phase 3: 수정 (Fix)

Task tool 사용:
subagent_type: fix-bugs
model: sonnet
prompt: |
  [Phase 1-2 진단 결과 포함]

  진단 결과를 바탕으로 버그를 수정해주세요.

  수정 원칙:
  - 최소 변경 원칙
  - exc_info=True 포함 (Python 로깅)
  - 에러 핸들링 추가 (필요시)
  - 같은 패턴의 버그가 다른 곳에 없는지 확인

수정 반영 [건너뛰기 금지]: fix-bugs 는 isolation: worktree 라 수정이 격리 트리에 남는다. Phase 4 로 가기 전에 그 수정(diff/브랜치)을 이 세션의 트리에 반영한다(방법: rules/parallel-worktree.md 의 반환·통합 절). 반영하지 않고 verify-code 를 부르면 옛 코드를 검증해 "해결됨"으로 오판한다. 반영하지 못했으면 Phase 4 를 건너뛰고 "수정 미반영"으로 보고한다.

재시도 상한: Phase 3→4 를 최대 3회까지만 돈다. 3회째에도 재현이 남거나, 무진전 2회(연속 두 번의 검증에서 실패 항목이 줄지 않음)이면 멈추고 현재까지의 원인 가설·시도·남은 실패를 사용자에게 보고한다. 같은 수정안을 반복해 시도하지 않는다.


Phase 4: 검증 (Verify)

Task tool 사용:
subagent_type: verify-code
model: haiku
prompt: |
  수정된 코드를 검증해주세요:
  [변경된 파일 목록]

  검증 항목:
  1. 에러 재현 → 해결 확인
  2. 빌드/컴파일 성공
  3. 타입 체크 통과
  4. 관련 테스트 통과
  5. 엣지 케이스 확인

출력 형식

Phase 1-2: 재현 및 격리

항목 내용
유형 [타입/런타임/빌드/외부API]
위치 [파일:라인]
재현 조건 [최소 재현 단계]
루트 원인 [원인 설명]
영향 범위 [함수/모듈/시스템]

Phase 3: 수정

[변경사항 diff 또는 설명]

Phase 4: 검증

[테스트/빌드 통과 여부]

예방 권장

[재발 방지를 위한 제안]

  • 테스트 추가
  • 타입 강화
  • 에러 핸들링 개선

04 同仓库更多 Skills

hashgraph-online
hashgraph-online/awesome-codex-plugins

worktable-review-with-annotations

Create, inspect, reply to, update, or resolve situated Worktable annotations. Use when feedback belongs to a Doc section, block, text range, or HTML Doc, or when the user asks to address existing review feedback and coordinate a requested artifact edit.

★ 1.6k
hashgraph-online
hashgraph-online/awesome-codex-plugins

worktable-find-and-synthesize-context

Find, assess, and synthesize context from Worktable Docs and Records. Use when the user asks what a workspace contains, wants workspace-backed research, needs current facts reconciled across artifacts, or requests a cited synthesis without changing workspace state.

★ 1.6k
hashgraph-online
hashgraph-online/awesome-codex-plugins

worktable-create-or-update-docs

Create, edit, rename, or maintain narrative Worktable Docs. Use for plans, decisions, briefs, notes, research syntheses, and other durable prose when the user requests a new artifact or a safe update to an existing one.

★ 1.6k
hashgraph-online
hashgraph-online/awesome-codex-plugins

worktable-create-or-manage-records

Organize repeated structured information as durable Worktable Records. Use for research datasets, inventories, directories, pipelines, trackers, and other collections whose items need identity, fields, filtering, links, validation, or individual updates.

★ 1.6k
hashgraph-online
hashgraph-online/awesome-codex-plugins

worktable-create-or-manage-interactive-html

Create or improve durable visual and interactive artifacts in Worktable. Use for dashboards, trackers, calculators, mini apps, slide presentations, and other requests that benefit from a polished HTML Doc.

★ 1.6k
hashgraph-online
hashgraph-online/awesome-codex-plugins

worktable-collaborate-threads

Read, answer, and hand off messages through durable Worktable threads with users or other authenticated participants. Use when the user asks to check addressed messages, reply to a participant, continue a thread, request another agent's help, wait briefly for a response, or watch for comments and messages sent to the agent.

★ 1.6k