GitHub Agentic Workflows 설계 템플릿 v0.1

목적

GitHub Agentic Workflows 후보를 바로 GitHub Actions write 자동화로 옮기지 않고, 먼저 JYP Labs의 작은 Closed Loop 기준으로 설계·검증하기 위한 템플릿이다.

공통 원칙

• read-only first: 처음에는 issue/log/diff/docs를 읽고 초안만 만든다.
• draft before write: label, assignment, comment, workflow rerun, PR 생성은 승인 후 단계다.
• evidence package: 모든 제안에는 근거 파일/로그/라인/URL이 필요하다.
• stop condition: 불확실하거나 보안·권한 문제가 있으면 needs_human_review로 멈춘다.

공통 Workflow Canvas

workflow_name: <name>
problem_statement: <what repeated team pain this handles>
trigger:
  event: <issue_opened | workflow_failed | docs_changed | manual_review>
  schedule: <optional>
inputs:
  - <issue body / labels / comments / workflow logs / diff / docs path>
agent_role: <triager | ci_analyst | docs_drift_checker>
allowed_actions:
  - read_issue
  - read_logs
  - read_diff
  - draft_summary
forbidden_actions_before_approval:
  - apply_label
  - assign_owner
  - post_comment
  - rerun_workflow
  - push_commit
  - create_pr
outputs:
  - classification
  - evidence
  - recommended_next_action
  - approval_required
verification:
  - <how a human can confirm the output>
audit_log:
  target: <OMW note | Slack thread | GitHub draft comment>
stop_conditions:
  - insufficient_evidence
  - sensitive_data_detected
  - permission_scope_unclear
  - destructive_or_external_side_effect

Template A — Issue Triage

Trigger

• 새 issue 생성
• 기존 issue가 24시간 이상 untriaged
• label이 없거나 owner가 불명확한 issue

Inputs

• issue title/body
• existing labels
• recent comments
• repository area map
• similar closed issues

Agent Role

triager: 문제 유형, 긴급도, 담당 영역, 필요한 추가 정보를 제안한다.

Output Schema

issue_triage_result:
  issue_id: <id>
  category: bug | feature | question | docs | ops | unclear
  priority: p0 | p1 | p2 | needs_review
  suggested_labels:
    - <label>
  suggested_owner: <team-or-person-or-needs_review>
  missing_information:
    - <question>
  evidence:
    - <quote-or-link>
  approval_required:
    - apply_label
    - assign_owner
    - post_comment

Human Approval Gate

• label 적용
• assignee 지정
• 외부 고객에게 보이는 comment 작성

Verification

• 분류 근거가 issue 본문이나 유사 issue에 연결되는가?
• 담당자 추천이 repo ownership과 맞는가?
• 민감 정보가 summary에 노출되지 않았는가?

Template B — CI Failure Analysis

Trigger

• GitHub Actions workflow 실패
• 같은 job이 2회 이상 연속 실패
• main branch 보호 규칙에 막힌 PR

Inputs

• workflow name/job name
• failing step log
• recent diff
• dependency file changes
• previous successful run

Agent Role

ci_analyst: 실패 원인 후보와 다음 확인 명령을 제안한다.

Output Schema

ci_failure_analysis:
  run_id: <id>
  failing_job: <job>
  suspected_cause: dependency | test_flake | environment | code_change | permission | unknown
  confidence: high | medium | low
  evidence:
    - <log excerpt>
    - <diff path>
  recommended_next_checks:
    - <command-or-inspection>
  safe_next_action: <draft_comment | ask_owner | rerun_after_approval | needs_review>
  approval_required:
    - rerun_workflow
    - push_fix
    - modify_ci_config

Human Approval Gate

• workflow rerun
• CI config 변경
• dependency pin 변경
• fix commit push

Verification

• log excerpt가 실제 원인 후보와 연결되는가?
• diff와 실패 지점이 시간상 연관되는가?
• flake 가능성을 과소평가하지 않았는가?

Template C — Documentation Drift

Trigger

• API/interface/config 변경 PR
• README/Docs와 코드 경로의 불일치 의심
• release note 작성 전 점검

Inputs

• changed files
• exported API/config/schema diff
• docs path map
• README/release note draft

Agent Role

docs_drift_checker: 문서 업데이트 필요 위치와 변경 요약을 제안한다.

Output Schema

docs_drift_result:
  changed_behavior:
    - <behavior>
  affected_docs:
    - path: <doc path>
      reason: <why affected>
  suggested_doc_update:
    - <bullet or paragraph draft>
  evidence:
    - <code path>
    - <existing doc quote>
  approval_required:
    - edit_docs
    - post_pr_comment
    - create_docs_pr

Human Approval Gate

• 문서 직접 수정
• PR comment 게시
• release note 변경

Verification

• 실제 behavior 변경이 있는가?
• 문서 업데이트 제안이 코드 diff를 과장하지 않는가?
• public docs에 민감 내부 정보를 노출하지 않는가?

JYP Labs 적용 순서

1. 내부 또는 sandbox repository에서 sample issue/log/diff를 준비한다.
2. 위 3개 template 중 하나만 선택한다.
3. read-only 분석 결과를 OMW note로 저장한다.
4. 사람이 결과를 검토해 오탐/누락을 표시한다.
5. 3회 이상 안정적으로 맞으면 GitHub draft comment 단계로 확장한다.
6. 실제 label/assignment/workflow rerun은 별도 승인 후 진행한다.

산출물 완료 기준

• trigger/input/output/approval/audit/stop condition이 모두 채워져 있다.
• write 작업은 모두 approval_required에 들어가 있다.
• 검증 가능한 evidence field가 있다.
• 실패 시 needs_human_review로 멈추는 조건이 있다.