[#53] Watcher 작업을 위한 AI 에이전트 역할과 실행 흐름을 구성한다

[opficdev]

🔗 연관된 이슈

• closed Watcher 작업을 위한 AI 에이전트 역할과 실행 흐름을 구성한다 #53

🎯 의도

Watcher 작업에서 역할별 책임과 실행 절차를 일관되게 적용하기 위한 AI 에이전트 문서 체계 구성

📝 작업 내용

📌 요약

• AGENTS.md를 작업 유형에 따라 저장소 지침을 연결하는 진입점으로 개편
• AI 에이전트의 역할, 권한, 실행 순서, 검증 기준을 .agents/에 정의
• 역할별 모델과 파일 접근 권한을 .codex/agents/*.toml에 구성
• 기존 문서 구조와 역할 이름을 유지하면서 세부 책임을 Watcher에 맞게 조정

🔍 상세

• AGENTS.md

  • 모든 작업에 적용할 문서와 작업 유형별 추가 문서를 안내하는 경로 구성
  • 아키텍처, PR, CI, 검증, release 작업별 누적 지침 연결

• .agents/rules/general.md

  • TypeScript strict mode, ESM, NodeNext, 명명 규칙과 외부 작업 제한 정의
  • GITHUB_TOKEN, WATCHER_GITHUB_TOKEN, OPENAI_API_KEY, DISCORD_WEBHOOK_URL 보호 기준 정의

• .agents/rules/architecture.md

  • branch 선별부터 Git 신호 수집, 결정론적 위험 분석, AI 보조 분석, report 생성과 전달까지의 소유권 정의
  • 결정론적 분석 결과와 AI 판단의 권한 분리
  • GitHub, OpenAI, Discord 연동과 secret, debug artifact 경계 정의
  • reusable workflow, CI, release packaging의 계약과 의존 방향 정의

• .agents/rules/project-workflows.md

  • Node 22와 npm run build 이후 npm test 실행 기준 정의
  • PR, review thread, CI, reusable workflow, release, consumer workflow 문서 처리 기준 정의
  • npm run watch와 GitHub write 작업의 실행 제한 정의

• .agents/roles.md

  • Planner, Implementer, Architecture Watcher, Code Reviewer, Verification Runner, GitHub/CI Analyst, Documentation Writer의 7개 역할 정의
  • 역할별 권한, 모델 등급, 승격 조건, task packet, 출력 형식, 완료 조건 정의

• .agents/workflows.md

  • issue 구현, 아키텍처 변경, review thread 반영, CI 실패 분석, 문서 작성, AI workflow 관리 절차 정의
  • 역할 실행 순서, 중단 조건, 검증 명령과 결과 전달 형식 정의

• .codex/agents/*.toml

  • architecture_watcher, code_reviewer, verification_runner, github_ci_analyst, documentation_writer의 5개 task_name 구성
  • 모든 역할에 gpt-5.3-codex-spark와 model_reasoning_effort = "medium" 지정
  • architecture_watcher, code_reviewer, github_ci_analyst에 sandbox_mode = "read-only" 지정
  • documentation_writer, verification_runner에 sandbox_mode = "workspace-write" 지정

• 검증

  • git diff --check 통과
  • 후행 공백 검사 결과 없음
  • TOML 5개 분석과 파일명·name·model 일치 검사 통과
  • 역할 제목, 모델, sandbox_mode 검사 통과
  • git status --short 기준 작업 트리 변경 없음
  • Markdown과 TOML만 변경되어 npm run build, npm test 미실행

• 변경 제외 범위

  • TypeScript 제품 코드와 테스트 변경 제외
  • README.md, package.json, .github/workflows/* 변경 제외
  • 실행 동작과 외부 consumer 계약 변경 제외
  • 활성 branch를 14일과 최대 30개 기준으로 선별한다 #41 활성 branch 선별 작업 제외

📸 영상 / 이미지 (Optional)

• 해당 없음

[gemini-code-assist]

Code Review

This pull request establishes a comprehensive AI agent role and workflow framework for the Watcher repository, defining specific agent roles, general and architecture-specific rules, executable workflows, and custom agent configurations, while refactoring AGENTS.md to serve as the central routing entrypoint. The review feedback suggests two key improvements: correcting a potentially reversed dependency direction (git -> branches) in the architecture rules to maintain proper layering, and replacing the ripgrep (rg) command with the more universally available grep in the verification script to ensure better compatibility on macOS environments.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.