agentleFS
develeepdeveleep/dev-gongbang/.claude/CLAUDE.md

dev-gongbang

CLAUDE.md1 starsChanged 19 days agoMITView on GitHub

스킬은 skills/<버킷>/<스킬 이름>/SKILL.md에 둔다. engineering/과 productivity/가 승격 버킷이다. 플러그인은 승격 버킷의 스킬만 정확히 담는다. 필요해지면 deprecated/ 같은 버킷을 같은 방식으로 추가한다. 1. frontmatter name은 폴더 이름과 같게 한다. 2. 버킷 README.md에 한 줄 설명과 SKILL.md 링크를 넣는다. 3. 승격 버킷이면 .claude-plugin/plugin.json의 skills 배열에 넣는다. in-progress/는 넣지 않는다. User-invoked 스킬이면 agents/openai.yaml을 둔다(아래 "도구 이름"). 4. 최상위 README.md와 README.en.md에 한 줄 설명, 사용 문서 링크, SKILL.md 링크를 넣는다. 승격 버킷은 "스킬" 절에, in-progress/는 "만드는 중인 스킬" 절에 두고, 각 절 안에서 호출…

  • Commits and pushes

The file

Files
CLAUDE.md

스킬 모음 운영 규칙

버킷

스킬은 skills/<버킷>/<스킬 이름>/SKILL.md에 둔다.

  • engineering/: 매일 하는 코드 작업
  • productivity/: 코드 밖의 일상 작업
  • in-progress/: 만드는 중. gongbang에 넣지 않고, marketplace.json의 gongbang-dev 항목이 폴더째 담는다

engineering/과 productivity/가 승격 버킷이다. 플러그인은 승격 버킷의 스킬만 정확히 담는다. 필요해지면 deprecated/ 같은 버킷을 같은 방식으로 추가한다.

스킬을 추가·이동·이름 변경할 때

  1. frontmatter name은 폴더 이름과 같게 한다.
  2. 버킷 README.md에 한 줄 설명과 SKILL.md 링크를 넣는다.
  3. 승격 버킷이면 .claude-plugin/plugin.json의 skills 배열에 넣는다. in-progress/는 넣지 않는다. User-invoked 스킬이면 agents/openai.yaml을 둔다(아래 "도구 이름").
  4. 최상위 README.md와 README.en.md에 한 줄 설명, 사용 문서 링크, SKILL.md 링크를 넣는다. 승격 버킷은 "스킬" 절에, in-progress/는 "만드는 중인 스킬" 절에 두고, 각 절 안에서 호출 방식 제목 아래에 둔다.
  5. 아래 "사용 문서" 규칙대로 스킬 문서와 문서 목록을 고친다.
  6. 사용자에게 배포할 변경이면 plugin.json의 version을 올린다. 설치된 플러그인은 버전이 바뀔 때만 갱신된다. 버전은 plugin.json에만 둔다. 버전을 올린 PR이 머지되면 아래 "릴리스" 절대로 태그와 릴리스를 만든다.
  7. scripts/check.py를 실행해 통과시킨다.
  8. in-progress/에서 승격할 때는 옮기기 전에 scripts/link-in-progress.sh --remove <스킬 이름>(project 범위면 --project --remove <스킬 이름>)으로 그 스킬의 로컬 링크를 지운다.

사용 문서

플러그인을 설치하는 사람이 읽는 문서다. 한국어가 기본이고, 영어판은 docs/en/에 같은 구조로 둔다. 한국어는 합니다체로 쓴다. 한국어 문서를 고치면 영어판도 같은 커밋에서 고친다.

  • docs/skills/<스킬 이름>.md: 스킬마다 한 페이지. 버킷과 상관없이 모든 스킬에 둔다. 섹션은 기존 페이지처럼 "언제 쓰나, 준비물, 진행 과정, 결과물, 커스텀, 함께 쓰는 스킬" 순서로 쓴다. 맨 위에는 언어 전환 줄, 위치 표시, 목차를, 맨 아래에는 이전·다음 링크를 둔다.
  • docs/README.md: 모든 스킬 페이지와 가이드의 목록
  • docs/customization.md: 스킬별로 고칠 파일 표가 있다

스킬을 추가하거나 지우면 스킬 페이지, 문서 목록, docs/customization.md 표를 함께 고치고, 앞뒤 스킬 페이지의 이전·다음 링크도 고친다. 순서는 최상위 README.md의 스킬 순서를 따른다. 승격할 때는 스킬 페이지의 버킷 값과 "만드는 중인 스킬" 안내를 고치고, 문서 목록과 README에서 절을 옮긴다. 스킬의 동작, 인자, 번들 파일이 바뀌면 그 스킬 페이지도 고친다.

Mod

mod는 mods/<플러그인 이름>/에 두고 marketplace.json에 따로 등록한다. 지금은 gongbang-mods 하나에 모든 mod를 묶는다.

  • mod 하나는 hooks/<mod 이름>.tsx에 (on: On) => void 함수로 만들고 hooks/register.tsx에서 부른다.
  • matcher 없는 hook은 플러그인 전체에서 이벤트마다 한 번만 걸 수 있다. 두 mod가 같은 이벤트를 쓰면 한 hook에서 둘 다 처리한다.
  • $.state 값은 types/index.d.ts의 'gongbang-mods' 아래에 선언한다.
  • mod 플러그인은 .claude-plugin/plugin.json을 두지 않고 매니페스트를 marketplace.json 항목("strict": false)에 적는다. 루트(./) 플러그인 안에 plugin.json이 중첩되면 claude.ai 동기화가 gongbang과 gongbang-dev를 거부한다.
  • 사용자에게 배포할 변경이면 marketplace.json의 gongbang-mods 항목 version을 올린다. 이 버전은 gongbang 버전과 따로 간다.
  • docs/mods.md와 docs/en/mods.md를 같은 커밋에서 고친다.
  • 외부 코드를 가져오면 원본 라이선스 파일을 그 폴더에 두고 docs/mods.md의 "출처" 절에 적는다.
  • scripts/check.py를 실행해 통과시킨다. mod마다 claude plugin validate와 claude plugin test를 돌린다.

Extras

extras/<이름>/에는 플러그인에 넣을 수 없어 사용자가 직접 설치하는 파일을 둔다. 지금은 statusline/과, mod 환경을 한 번에 설정하는 setup.sh가 있다. mod나 외부 mod 목록이 바뀌면 setup.sh도 고친다. 버전을 매기지 않고, 설치 방법과 동작은 docs/mods.md와 docs/en/mods.md에 함께 적는다.

릴리스

plugin.json의 version을 올린 PR이 머지되면, 최신 master에서 다음을 실행한다. 태그 이름은 gongbang--v<버전>이다.

claude plugin tag . --push
gh release create gongbang--v<버전> --generate-notes

claude plugin tag는 plugin.json과 marketplace.json이 어긋나거나 작업 트리에 커밋하지 않은 변경이 있으면 태그를 만들지 않는다. 릴리스 노트는 직전 태그 뒤에 머지된 PR로 만들어진다.

호출 방식

모든 스킬은 둘 중 하나다. README.md들도 이 둘로 나눠 적는다.

  • User-invoked: frontmatter에 disable-model-invocation: true. 사람이 이름을 입력할 때만 실행된다. description은 사람이 읽는 한 줄 요약으로 쓰고 트리거 문구를 넣지 않는다.
  • Model-invoked: 기본값. description에 언제 쓰는지 트리거 문구를 구체적으로 적어 모델이 스스로 고를 수 있게 한다.

다른 스킬을 쓰게 할 때는 ../다른-스킬/FILE.md 같은 폴더 간 링크 대신 "<이름> 스킬을 불러와 그 지시를 따른다. 스킬 도구가 없으면 그 스킬의 SKILL.md를 읽는다"고 적는다. User-invoked 스킬은 다른 스킬에서 불러올 수 없으니 사용자에게 실행을 안내한다.

도구 이름

스킬은 Claude Code, OMP, Codex에서 함께 쓴다. 본문에는 특정 에이전트의 도구 이름(AskUserQuestion, Agent, Skill, WebFetch, request_user_input, spawn_agent 등)을 쓰지 않고, 행동과 그 행동을 못 할 때의 폴백을 같은 문장에 쓴다.

  • 묻기: "사용자에게 묻는다. 선택지를 보여 주는 질문 도구가 있으면 그것으로, 없으면 번호 목록으로 묻고 답을 기다린다."
  • 서브에이전트: "새 컨텍스트로 서브에이전트를 띄운다. 띄울 수 없으면 같은 세션에서 차례로 한다."
  • 스킬: "<이름> 스킬을 불러와 그 지시를 따른다. 스킬 도구가 없으면 그 스킬의 SKILL.md를 읽는다."
  • 웹: "웹 페이지를 가져와 읽는다." 못 가져오면 그렇다고 알린다.

"AskUserQuestion(OMP는 ask)"처럼 에이전트별 이름을 괄호로 나열하지 않는다. 한 에이전트에서만 되는 기능(claude -p 등)은 "있으면 …, 없으면 건너뛰고 알린다"로 쓴다. prompt-builder/reference/models/처럼 프롬프트 내용으로 도구를 다루는 글은 예외다. disable-model-invocation: true인 스킬은 Codex용 agents/openai.yaml에 policy.allow_implicit_invocation: false를 함께 둔다. scripts/check.py가 둘 다 검사한다.

Eval

스킬마다 evals/<스킬 이름>/에 동작 케이스를, evals-trigger/<스킬 이름>/에 트리거 케이스를 둔다. 실행 명령은 README.md에 있다. eval은 저장소의 스킬을 바로 읽으므로 실행 중에는 skills/를 수정하지 않는다.

커밋

한국어로 쓴다. 제목은 <유형>: <작업 요약>, 빈 줄 다음에 작업 내역을 - 목록으로 적는다.

feature: prompt-builder에 Opus 5.5 모델 가이드 추가

- reference/models/opus-5-5.md 작성
- 모델 선택 질문에 Opus 5.5 항목 추가
- plugin.json 버전 1.2.0으로 올림

유형:

  • feature: 새 스킬이나 스킬의 새 동작
  • fix: 잘못된 동작 수정
  • docs: README, CLAUDE.md 등 문서
  • refactor: 동작 변화 없는 구조·문구 정리
  • eval: eval 케이스나 채점 기준
  • chore: 설정, 스크립트, 매니페스트 등 그 밖의 작업

형식:

  • 유형은 위 목록의 영어 소문자 그대로 쓰고, 콜론 뒤에 한 칸 띄운다.
  • 제목은 50자 이내로 쓰고 끝에 마침표를 찍지 않는다. 요약은 "추가", "수정", "삭제"처럼 명사로 끝낸다.
  • 작업 내역은 한 줄에 변경 하나씩 적고, 끝에 마침표를 찍지 않는다. 한 줄이 72자를 넘으면 나눠 쓴다.
  • 파일, 스킬, 명령 이름은 원래 표기 그대로 쓴다.
  • 이유를 남길 필요가 있으면 작업 내역 다음에 빈 줄을 두고 한두 문장으로 적는다.
  • 커밋 하나에는 유형 하나만 담는다. 여러 유형이 섞이면 커밋을 나눈다.

Co-Authored-By 등 AI 작성 표시 줄은 넣지 않는다.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.