chore(agents): claude.dev 권고를 에이전트 설정에 반영

[pbk95120]

📝 작업 내용 요약

claude.dev 블로그의 컨텍스트·스킬 운영 권고(함정은 적고 규칙은 줄이기, 검증 스킬, 긴 스킬은 파일로 분리)를 우리 에이전트 설정에 반영했습니다. 코드 변경은 없습니다.

• AGENTS.md: 자주 밟는 함정 섹션 추가(BACKEND_API_URL 없으면 빌드 실패, 브라우저 dev 서버는 401이라 데이터 없음, CSS 키프레임은 마운트 때만 재생, overflow-y-auto 끝 padding 사라짐, 포커스 링 통일). 작업 원칙에 멈출 때와 이어 갈 때 기준 추가
• verify-web 스킬 신설: Playwright + page.route 목으로 모바일 뷰포트(375×812) 화면을 검증하는 절차와 함정(목 누락 시 fixtures.ts가 실패 처리, 3100번 이전 빌드 재사용, 네이티브 브리지 없음, 애니메이션 도중 캡처)
• pr-create: 릴리즈 모드와 Codex 위임 모드를 references/로 분리(본문 321줄 → 약 270줄). 기존 주의사항은 각 Step과 중복이라 지우고, 실제로 막혔던 사례로 함정 섹션을 새로 둠
• next16-rn-reviewer: 출력에 확인하지 못한 것 섹션을 추가하고, 🔴는 머지를 막을 문제에만 쓰도록 기준 명시
• run(실행)과 local-build(빌드 문제 해결·환경 셋업)의 설명을 나눠 트리거가 겹치지 않게 함

✅ 체크리스트

• develop 브랜치의 최신 코드를 pull 받았나요?
• 빌드가 통과했나요?
• vitest 테스트가 통과했나요?
• Playwright e2e가 통과했나요?

🤖 AI 리뷰

Claude (next16-rn-reviewer)

판정: 🟡 사소한 지적과 함께 승인 → 지적 8건 모두 반영(마지막 커밋)

• 🟠 AGENTS.md 멈춤 기준이 pr-create의 되돌릴 수 있는 승인 게이트(분할 판단, 리뷰 결과 확인)와 충돌 → 예외에 "스킬이 정한 승인 게이트"를 추가
• 🟡 포커스 클래스에 focus-visible:outline-none 누락 → 추가
• 🟡 run 설명에 빌드 트리거가 남아 local-build와 겹침 → run을 실행 전용으로 좁힘
• 🟡 release.md가 "Step 0~8 그대로"라고 해 Step 2.5 생략과 어긋남 → 생략 명시
• 🟡 Step 3 빌드 명령에 BACKEND_API_URL이 없어 첫 실행이 항상 실패 → 명령에 직접 넣음
• 🟡 분리하면서 "pnpm 사용" 한 줄이 사라짐 → 강제 사용 규칙에 복원
• 🟡 verify-web 스크린샷 실제 경로(apps/web/test-results/) 명시
• 🟡 검증용 spec을 커밋하면 e2e 게이트에 영구 포함된다는 점 추가

확인하지 못한 것: codex:codex-rescue의 --write 기본값(플러그인이 레포 밖), apps/native/.env.production 항목(추적되지 않는 파일). 둘 다 기존 문서를 옮기기만 한 부분입니다.

Codex 교차 리뷰

생략했습니다. 로컬 Codex CLI가 0.142.5이고, docs/harness.md에 기록된 대로 이 버전은 gpt-6-astra 호출이 거부됩니다. 다른 모델로 대신 돌리지 않았습니다.

💬 기타 코멘트

• 문서·스킬만 바뀌어 빌드·vitest는 돌리지 않았습니다. e2e는 verify-web에 적은 명령(pnpm --filter web exec playwright test e2e/goal.spec.ts)이 그대로 동작하는지 확인하는 용도로 실행했습니다(2 passed).
• 검토했지만 반영하지 않은 것
  • 리뷰어 effort 지정: docs/harness.md가 "프로젝트에서 reasoning effort를 지정하지 않는다"로 정해 둬서 제외
  • vercel 스킬 정리: apps/web이 Vercel에 연결돼 있어 배포 스킬도 유효하므로 유지
  • 번들 크기 래칫 CI: 기준치를 정하는 작업이 따로 필요해서 별도 PR로 미룸
• AGENTS.md 함정 목록은 실제로 겪은 것만 적었습니다. 새로 막히는 곳이 생기면 같이 늘려 주세요.

🤖 Generated with Claude Code

변경 사항

• AGENTS.md에서 사용자 확인이 필요한 상황에 스킬의 승인 게이트를 포함하고, 포커스 표시 권장 클래스를 구체화했습니다.
• pr-create의 빌드 명령에 BACKEND_API_URL을 추가하고, 환경변수 누락 시의 안내를 수정했습니다. 릴리즈 모드에서는 대형 PR 분할 판단 단계를 건너뛰도록 명시했습니다.
• run 스킬 설명을 로컬 실행으로 한정하고, 빌드 오류 해결과 환경 설정은 local-build를 사용하도록 안내했습니다.
• verify-web에 스크린샷 저장 경로와 확인용 테스트 정리 기준을 추가했습니다.

문서와 스킬 파일만 변경되었습니다. 테스트 실행 결과는 제공된 변경 내역에서 확인할 수 없습니다.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
28th-web-team-3-fe-web-dev	Ready	Preview	Oct 1, 2026 11:48pm UTC

1 Skipped Deployment

Project	Deployment	Actions	Updated
28th-web-team-3-fe-admin	Ignored		Oct 1, 2026 11:48pm UTC

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

Note

Currently processing new changes in this PR. This may take a few minutes, please wait...

⚙️ Run configuration

Configuration used: Repository: YAPP-Github/28th-Web-Team-3-FE/.coderabbit.yaml

Review profile: CHILL

Plan: Advanced

Run ID: e4d6246d-6e99-49b6-8b76-7ad8dbec2fc8

📥 Commits

Reviewing files that changed from the base of the PR and between a0c756b and 4fe8e7c.

⛔ Files ignored due to path filters (8)

• .agents/agents/next16-rn-reviewer.md is excluded by !.agents/**
• .agents/skills/local-build/SKILL.md is excluded by !.agents/**
• .agents/skills/pr-create/SKILL.md is excluded by !.agents/**
• .agents/skills/pr-create/references/codex-delegate.md is excluded by !.agents/**
• .agents/skills/pr-create/references/release.md is excluded by !.agents/**
• .agents/skills/run/SKILL.md is excluded by !.agents/**
• .agents/skills/verify-web/SKILL.md is excluded by !.agents/**
• .claude/skills/verify-web is excluded by !.claude/**

📒 Files selected for processing (1)

• AGENTS.md

 ___________________________________________________________________________
< I love a good shortcut. This is a great shortcut to production incidents. >
 ---------------------------------------------------------------------------
  \
   \   \
        \ /\
        ( )
      .( o ).

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Autopilot is currently an internal CodeRabbit preview.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}