allar-skills-update

한 줄 설명: 비개발자의 자연어 요청을 이 저장소의 새 스킬 추가나 기존 스킬 업데이트 작업으로 바꾸는 공용 유지보수 스킬이다.

언제 사용해야 하는지

• 기존 스킬 설명, 예시, 체크리스트, 출력 형식을 업데이트해야 할 때
• 비개발자가 새 스킬을 이 저장소에 추가해 달라고 요청할 때
• 새 스킬 추가 후 README.md의 목록, 구조, 사용 안내도 같이 맞춰야 할 때
• 기존 스킬 수정 후 README.md 설명이나 스킬 목록도 같이 맞춰야 할 때
• 어떤 역할 폴더에 넣어야 할지 애매한 공용 스킬을 정리해야 할 때
• 저장소 구조는 유지하되, 표현과 문서를 실사용자 관점으로 다듬어야 할 때

먼저 확인해야 할 파일

• 저장소 개요와 현재 스킬 목록은 README.md에서 확인한다.
• 기존 스킬을 수정하는 요청이면 해당 skills/<area>/<skill-name>/SKILL.md를 먼저 읽는다.
• 새 스킬이 필요한 요청이면 어떤 역할이 주로 쓰는지 확인하고, 적절한 영역 폴더를 고른다.

변경 전 확인 규칙

• 실제 수정에 들어가기 전에, 이번 요청이 기존 스킬 업데이트인지 새 스킬 추가인지 먼저 사용자에게 확인받는다.
• 사용자가 이미 "기존 스킬 고쳐줘", "새 스킬 만들어줘"처럼 명확히 말했으면 다시 묻지 않는다.
• 요청이 섞여 있거나 표현이 애매하면, 작업을 시작하기 전에 짧고 닫힌 질문으로 먼저 구분한다.
• 이 확인이 끝나기 전에는 어떤 스킬을 수정할지, 새로 만들지 확정하지 않는다.

먼저 물어볼 기본 질문

• 이번 요청은 기존 스킬 업데이트야, 아니면 새로운 스킬 추가야?

확인 후 처리 규칙

• 기존 스킬 업데이트로 확인되면, 어떤 스킬을 바꾸는지와 수정 범위를 이어서 확인한다.
• 새 스킬 추가로 확인되면, 어떤 역할 영역에 둘지와 기대 출력 형식을 이어서 정리한다.
• 둘 다 필요하다고 답하면, 기존 스킬 업데이트와 새 스킬 추가를 분리해서 순서를 정한다.

작업 시작 전 환경 점검

• 먼저 현재 작업 디렉터리가 이 저장소인지 확인한다.
• git remote -v로 어떤 원격 저장소를 기준으로 작업하는지 확인한다.
• gh --version으로 GitHub CLI 설치 여부를 확인한다.
• gh가 없으면 설치부터 진행한다.
• gh auth status로 로그인 상태를 확인한다.
• 인증이 안 되어 있으면 먼저 로그인 절차를 안내하거나 진행한다.
• 원본 기본 브랜치에 직접 push 하지 않고, 항상 작업 브랜치와 PR로 반영한다.

gh가 없을 때 기본 처리

• macOS라면 brew install gh를 우선 사용한다.
• Homebrew가 없거나 설치 방식이 다르면 운영 환경에 맞는 공식 설치 경로를 확인한다.
• 설치가 끝나면 다시 gh --version으로 정상 설치를 확인한다.

GitHub 로그인 확인 규칙

• gh auth status가 실패하면 로그인 전제로 작업을 계속하지 않는다.
• 로그인이 필요하면 gh auth login으로 인증을 진행한다.
• 저장소 접근이 필요한 작업이면 GitHub 계정이 어느 조직에 연결되어 있는지도 함께 확인한다.
• 로그인은 되었지만 저장소 접근이 안 되면, 인증 문제와 권한 문제를 구분해서 본다.

PR 우선 원칙과 포크 처리 규칙

• 원본 저장소의 기본 브랜치에는 직접 push 하지 않는다.
• 권한이 있더라도 항상 작업 브랜치를 만들고 PR로 반영한다.
• 원본 저장소에 작업 브랜치를 push 할 권한이 없으면 작업을 멈추지 말고 포크 기반 흐름으로 전환한다.
• 포크가 없으면 gh repo fork로 먼저 포크를 만든다.
• 포크 후에는 origin이 내 포크를 가리키는지, 원본 저장소는 upstream으로 남아 있는지 확인한다.
• 브랜치는 포크 기준으로 새로 만들고, 변경은 포크에 push 한다.
• PR은 포크 브랜치에서 원본 저장소의 기본 브랜치로 연다.

원본 저장소에 작업 브랜치를 push 할 수 있을 때 기본 흐름

1. 최신 기본 브랜치를 기준으로 새 브랜치를 만든다.
2. 필요한 파일을 수정한다.
3. 변경 내용을 검토한다.
4. 작업 브랜치를 원본 저장소에 push 한다.
5. gh pr create로 PR을 만든다.
6. 기본 브랜치에 직접 push 하지 않았는지 마지막으로 확인한다.

원본 저장소에 작업 브랜치를 push 할 수 없을 때 포크 흐름

1. gh repo fork로 내 계정 아래 포크를 만든다.
2. 로컬 원격 구성이 꼬이지 않았는지 확인한다.
3. 원본 저장소는 upstream, 내 포크는 origin이 되도록 맞춘다.
4. 작업 브랜치를 만든다.
5. 수정 후 브랜치를 내 포크에 push 한다.
6. gh pr create --repo <upstream-owner>/<repo> 형식으로 원본 저장소 대상 PR을 만든다.
7. PR 본문에는 왜 포크 기반으로 작업했는지 짧게 남긴다.

권한 또는 인증 이슈가 있을 때 응답 규칙

• gh 미설치, 로그인 실패, 조직 접근 불가, 저장소 권한 부족 중 어디에서 막혔는지 분리해서 설명한다.
• 막힌 이유를 모르면 "권한 없음"으로 뭉뚱그리지 말고, 확인한 단계와 실패 지점을 적는다.
• 원본 저장소에 직접 반영하지 못하더라도 포크와 PR로 계속 진행 가능하면 그 경로로 마무리한다.
• 로그인이나 권한 부족 때문에 실제 원격 작업을 못 했으면, 로컬 변경 완료와 남은 원격 작업을 구분해서 설명한다.

요청 해석 규칙

• 비개발자의 표현을 그대로 개발 용어로 되묻지 말고, 실제 저장소 작업 단위로 바꿔 이해한다.
• 사용자의 첫 요청만으로 신규/수정 여부가 확실하지 않으면, 먼저 그 구분부터 확인한다.
• 새 스킬 추가와 기존 스킬 업데이트가 섞여 있으면, 먼저 기존 스킬을 어떻게 바꿔야 하는지부터 정리한다.
• 요청은 먼저 아래 네 가지 중 하나로 분류한다.
  • 새 스킬 추가
  • 기존 스킬 업데이트
  • README 또는 설치 안내 수정
  • 폴더 구조 또는 분류 정리
• 여러 작업이 섞여 있으면, 사용자 요청과 직접 연결된 변경부터 처리한다.
• 요청이 모호해도 바로 멈추지 말고, 저장소에서 확인 가능한 정보로 최대한 진행한다.
• 정말 막히는 항목만 짧고 구체적으로 확인한다.

영역 선택 규칙

• 여러 직군이 공통으로 쓰거나, 이 저장소 자체를 유지보수하기 위한 스킬이면 skills/common/에 둔다.
• 기획 산출물 작성 중심이면 skills/planning/에 둔다.
• 디자인 작업 산출물 중심이면 skills/design/에 둔다.
• 프론트엔드 구현 또는 구조화 가이드 중심이면 skills/frontend/에 둔다.
• 백엔드 API, 데이터, 서버 운영 규칙 중심이면 skills/backend/에 둔다.
• 영역이 애매하면 "누가 가장 자주 쓰는가"보다 "이 스킬이 어떤 결과물을 만들게 하는가"를 기준으로 정한다.

새 스킬 추가 규칙

1. 스킬 목적을 한 문장으로 정리한다.
2. 폴더명과 name은 영문 소문자 kebab-case로 만든다.
3. SKILL.md에는 아래 흐름이 보이도록 작성한다.
   • 한 줄 설명
   • 언제 사용해야 하는지
   • 입력으로 기대하는 정보 또는 전제
   • 반드시 지켜야 할 출력 형식이나 작업 절차
   • 품질 체크리스트
   • 예시 요청
4. 본문은 비개발자도 이해할 수 있는 한국어 중심으로 쓴다.
5. 장황한 설명보다 바로 실행 가능한 규칙, 체크리스트, 템플릿 위주로 작성한다.
6. 참고 자료가 길어질 때만 references/를 추가한다.
7. 스킬을 새로 만들었으면 README.md의 구조와 포함된 스킬 목록도 함께 갱신한다.

기존 스킬 수정 규칙

• 기존 스킬 업데이트 요청이면 이 스킬을 기본 진입점으로 사용한다.
• 기존 스킬의 문체와 섹션 구조를 가능한 한 유지한다.
• 이미 있는 예시가 여전히 유효하면 살리고, 오해를 부르는 표현만 고친다.
• 사용자 요청이 "쉽게 바꿔줘", "비개발자도 쓰게 해줘"라면 전문 용어를 줄이고 입력 예시를 보강한다.
• 링크, 정책, 수치, 회사 규칙은 입력이나 저장소에 없는 내용을 임의로 만들지 않는다.
• 스킬 이름이나 폴더를 바꾸면 README.md와 내부 링크도 빠짐없이 고친다.

기존 스킬 업데이트 기본 흐름

1. 어떤 스킬을 바꿔야 하는지와 왜 바꾸는지 먼저 짧게 정리한다.
2. 해당 스킬의 현재 SKILL.md를 읽고, 유지할 부분과 바꿔야 할 부분을 나눈다.
3. 요청이 문구 수정인지, 구조 개편인지, 예시 보강인지 구분한다.
4. 필요한 범위만 수정하고, 사용자 요청과 무관한 다른 스킬은 건드리지 않는다.
5. 변경 결과가 README 설명과 어긋나면 함께 갱신한다.

README 동기화 체크리스트

• 저장소 구조 트리에 새 영역이나 새 스킬 흐름이 반영되어 있는가
• 포함된 스킬 표에 이름, 설명, 경로가 맞게 반영되어 있는가
• 새 스킬 만들기 섹션의 폴더 안내가 현재 구조와 맞는가
• 설치 또는 업데이트 방법이 바뀌지 않았다면 불필요하게 건드리지 않았는가
• README 설명이 실제 tracked 파일 기준과 어긋나지 않는가
• 비개발자용 안내에 권한이 없을 때 포크와 PR로 처리할 수 있다는 맥락이 필요한지 확인했는가

질문이 꼭 필요한 경우

• 사용자가 새 스킬 추가와 기존 스킬 업데이트 중 어느 쪽인지 분명히 말하지 않았을 때
• 새 스킬의 목적이 너무 넓어서 한 개 스킬로 묶기 어려울 때
• 어느 역할 영역에 넣어야 할지 결정하면 의미가 크게 달라질 때
• 사용자가 원하는 산출물 형식이 기존 규칙과 정면으로 충돌할 때

질문은 한 번에 많이 하지 말고, 아래처럼 바로 답할 수 있게 짧게 묻는다.

• 이 스킬은 기획 문서 작성용이야, 아니면 여러 팀이 공통으로 쓰는 운영용이야?
• 이번 요청은 기존 스킬 업데이트야, 아니면 새로운 스킬 추가야?
• 이번에는 새 스킬 추가가 목적이야, 아니면 기존 README 정리까지 같이 원해?
• 출력 형식을 회사 표준 템플릿으로 강제해야 해, 아니면 초안 중심이면 돼?

하지 말아야 할 것

• 스킬 폴더 안에 불필요한 README.md, CHANGELOG.md, QUICK_GUIDE.md를 만들지 않는다.
• 사용자 요청과 관계없는 다른 스킬까지 한꺼번에 정리하지 않는다.
• 비개발자가 이해하기 어려운 용어를 설명 없이 남겨 두지 않는다.
• README를 최신 상태로 맞춰야 하는 상황에서 문서 반영을 빼먹지 않는다.
• 원본 저장소의 기본 브랜치에 직접 push 하지 않는다.

작업 완료 후 응답 규칙

• 어떤 파일을 바꿨는지 짧게 요약한다.
• 새로 만든 스킬이면 어디에 추가했는지와 왜 그 영역을 골랐는지 적는다.
• 가정이 있었다면 한두 줄로 분리해서 적는다.
• 원격 반영까지 했다면 어떤 작업 브랜치에서 PR을 만들었는지 짧게 적는다.
• 원격 반영을 못 했다면 gh 설치, 로그인, 권한, 포크 여부 중 어디까지 완료했는지 적는다.
• 테스트할 것이 없으면 문서/스킬 변경이라 별도 실행 테스트는 없다고 명시한다.

예시 요청

• prd-writer 설명이 너무 딱딱해. 기획자가 바로 이해할 수 있게 기존 스킬 내용을 다듬어줘.
• issue-writer에 QA 팀도 바로 쓸 수 있는 완료 조건 예시를 추가해줘. README에 적힌 설명도 같이 맞춰줘.
• 운영팀이 회의 메모를 정리할 때 쓸 새 스킬이 필요해. 새로 만드는 게 맞는지 보고 추가해줘.
• 이 요청이 기존 스킬 수정으로 끝나는지, 새 스킬을 만들어야 하는지 잘 모르겠어. 먼저 확인해보고 진행해줘.