Claude Code·Codex에 팀 코딩 규칙을 심어 주는 agent skills (adlc-team-skills)

TL;DR Highlight

세션 시작 때 팀 규칙 목차만 주입하고 필요할 때 본문을 불러오는 스킬 모음

Who Should Read

개인 CLAUDE.md가 팀원마다 달라 코딩 에이전트가 팀 규칙을 모르고 일해서 고민인 팀 개발자

Core Mechanics

세션 시작에 규칙 목차만 주입
- team-boot가 session_start 훅으로 규칙 이름과 한 줄 설명만 넣는다.
- 분량은 약 100토큰이고, 규칙 본문은 작업이 맞을 때 on-demand로 불러온다.
규칙은 git 저장소로 팀이 공유
- team-ai-directives 저장소에 두고 PR로 리뷰한다.
- 한 PC에만 있는 개인 CLAUDE.md 문제를 없애려는 구조다.
코드 전에 계약부터 쓰게 한다
- factory-mission이 목표·제약·비목표·성공 기준을 먼저 쓰게 한다.
- 이후 specify → plan → implement ↔ converge 순서로 가고 게이트와 circuit breaker(반복 폭주 차단 장치)가 있다.
세션 학습을 기록으로 남긴다
- team-levelup이 세션 종료 시 어려웠던 수정을 CDR(Context Directive Record)로 뽑아 신뢰도 점수를 매긴다.
- 승인된 CDR은 팀 저장소에 draft PR로 올라간다.
평가는 이진 채점기 중심이다
- evals-* 스킬은 코드로 검증 가능한 부분은 이진 체크로 만든다.
- 정적 체크가 안 되는 부분에만 LLM 심사를 쓰고 holdout split과 TPR/TNR로 검증한다.

Community Reactions

악성코드가 들어갔다는 경고
- 커밋 74f317d에서 .claude와 .vscode에 숨김 파일 5개가 추가됐다는 댓글이 있었다.
- vscode tasks.json 자동 실행이나 Claude 세션 시작 훅으로 난독화 페이로드를 돌려 GitHub·AWS·K8s 토큰 등을 빼 간다는 분석이다.
- npx 설치와 VSCode 열기를 피하고 키를 교체하라는 의견이었다.
컨텍스트를 채울수록 규칙을 잊는다는 의견
- 에이전트 가드레일보다 ArchUnit·정적 분석기 같은 결정론적 도구가 낫다는 의견이었다.
- 규칙이 많아져 토큰 소모, 리뷰 부담, 작업 시간이 늘기만 할 것 같다는 반응도 있었다.
스킬·AGENTS.md 없이 써 보라는 경험
- 스킬과 시스템 프롬프트 없이 시작하면 최신 모델이 더 잘한다는 경험이 공유됐다.
- 같은 작업을 9번 돌려 비교한 링크를 제시했고, 작성자가 smol 개발자라고 밝혔다.
비슷한 팀 스킬 저장소 운영 경험
- git 저장소에 회사 스킬을 모으고 "update company skills" 스킬로 ~/.codex에 연결해 쓴다는 댓글이 있었다.
- 기계 검증 가능한 것은 테스트·린터로 옮기고, 각 실행에 규칙 리비전을 기록하자는 제안도 있었다.
README가 AI가 쓴 것 같아 이해하기 어렵다는 반응

How to Apply

오늘 팀 규칙을 목차+본문으로 쪼개기
- 지금 CLAUDE.md에서 규칙마다 이름과 한 줄 설명 목차를 만든다.
- 본문은 별도 파일로 빼고 목차만 항상 읽도록 지시한다.
설치 전 저장소 커밋부터 확인하기
- npx로 실행하기 전에 .claude와 .vscode 숨김 파일과 최근 커밋 diff를 직접 본다.
- 의심 파일이 있으면 설치하지 말고 격리된 환경에서만 열어 본다.
기계 검증 가능한 규칙은 CI로 옮기기
- 규칙 중 린터나 테스트로 확인되는 항목을 골라 CI 체크로 만든다.
- 프롬프트에는 의도와 워크플로만 남긴다.
규칙 효과를 규칙 없이 비교하기
- 규칙 하나를 빼고 같은 작업을 돌려 통과 여부를 비교한다.
- 모델이 그냥 통과하면 그 규칙은 삭제한다.

Try It

복사해서 바로 해보기

# Claude Code에 붙여넣는 프롬프트 (adlc-team-skills 아이디어의 간이 버전)

내 CLAUDE.md를 읽고 아래 작업을 해줘.
{{CLAUDE.md 내용}}

1. 규칙마다 '이름 | 한 줄 설명' 목차를 만들어줘. 전체 100토큰 안팎으로.
2. 규칙 본문은 rules/{이름}.md 파일로 분리해줘.
3. 새 CLAUDE.md에는 목차만 넣고, 작업과 관련된 규칙만 본문을 읽으라는 지시를 추가해줘.
4. 린터나 테스트로 자동 검증할 수 있는 규칙은 따로 표시해줘.

이어서 해 볼 것: 같은 작업 {{작업}}을 규칙 없이 한 번, 목차 방식으로 한 번 돌려 결과를 비교해 봐.

Terminology

Agent SkillsSKILL.md 파일로 에이전트에게 특정 작업 방법을 알려 주는 표준 형식이다. 매뉴얼을 서랍에 넣어 두고 필요할 때 꺼내 보게 하는 것과 비슷하다.

CDRContext Directive Record. 세션에서 얻은 어려운 수정 노하우를 기록해 팀 규칙 저장소에 올리는 단위다.

ADR/PDR/ChDR각각 아키텍처, 제품, 변경에 대한 결정 기록이다. 왜 그렇게 정했는지 남기는 회의록과 비슷하다.

circuit breaker에이전트가 같은 실패를 반복할 때 루프를 끊는 안전장치다. 전기 차단기처럼 과열되면 내려간다.

TPR/TNR채점기가 맞는 걸 맞다고, 틀린 걸 틀리다고 얼마나 잘 판정하는지 보는 지표다.