shopl-sprint-planner
v0.2.8
Published
Installer for Shopl sprint planner workflows across Codex and Claude Code.
Maintainers
gyub.sReadme
Shopl Sprint Planner
Shopl 스프린트 플래닝 워크플로우를 Codex 또는 Claude Code에서 사용할 수 있게 설치하는 패키지입니다.
이 패키지는 한 가지 방식만 지원하지 않습니다. 사용하는 도구와 원하는 동작 방식에 따라 설치 모드를 나눠서 제공합니다.
설치 모드 요약
설치 모드는 터미널에 모드 이름만 입력하는 것이 아닙니다.
항상 아래처럼 설치 명령 + --mode 형태로 실행합니다.
npm install -g shopl-sprint-planner
shopl-sprint-planner --mode codex-skill즉, codex-skill, codex-project, claude-skill, claude-command 같은 값은 "설치 프로그램이 어떤 방식으로 동작할지"를 고르는 옵션입니다.
| 모드 | 대상 | 설치 위치 | 호출 방식 |
| --- | --- | --- | --- |
| codex-skill | Codex | $CODEX_HOME/skills 또는 ~/.codex/skills | $shopl-sprint-planner 명시 호출 |
| codex-project | Codex | 프로젝트 루트의 AGENTS.md | 프로젝트 규칙 파일 기반 |
| claude-skill | Claude Code | $CLAUDE_CONFIG_DIR/skills 또는 ~/.claude/skills | /shopl-sprint-planner 명시 호출 |
| claude-command | Claude Code | 프로젝트 루트의 .claude/commands/shopl-sprint-planner.md | /shopl-sprint-planner 명시 호출 |
| claude-memory | Claude Code | 프로젝트 루트의 CLAUDE.md | 프로젝트 메모리 기반 |
| project | Codex + Claude Code | AGENTS.md + .claude/commands/... | Codex 프로젝트 규칙 + Claude 명령 동시 설치 |
요구 사항
- Node.js 18 이상
- npm
- Codex 또는 Claude Code
빠른 시작
가장 권장하는 기본 설치는 전역 설치 후 codex-skill 모드로 실행하는 방식입니다.
npm install -g shopl-sprint-planner
shopl-sprint-planner --mode codex-skill이 명령은 아래 경로 중 하나에 스킬을 설치합니다.
$CODEX_HOME/skills/shopl-sprint-plannerCODEX_HOME이 없으면~/.codex/skills/shopl-sprint-planner
그다음 새 Codex 세션에서 아래처럼 명시적으로 호출해서 사용합니다.
$shopl-sprint-planner를 사용해서 Shopl 상위 Jira 티켓을 기준으로 필요한 질문을 한 번에 하나씩 진행하고, 필요하면 실제 하위 티켓을 먼저 만든 뒤 docs/work-plans 문서를 작성해줘.참고:
- 이 설치는 현재 사용자 계정의 Codex 환경 전체에 적용됩니다.
- 특정 프로젝트에만 한정되지 않습니다.
- 이 스킬은 자동 참조용이 아니라 명시 호출 전용으로 설정되어 있습니다.
Claude Code에서도 모든 프로젝트에서 사용할 전역 Skill로 설치할 수 있습니다.
npm install -g shopl-sprint-planner
shopl-sprint-planner --mode claude-skill이 명령은 아래 경로 중 하나에 Claude Code personal skill을 설치합니다.
$CLAUDE_CONFIG_DIR/skills/shopl-sprint-plannerCLAUDE_CONFIG_DIR이 없으면~/.claude/skills/shopl-sprint-planner
설치 후 새 Claude Code 세션에서 다음처럼 명시적으로 호출합니다.
/shopl-sprint-planner1. Codex 전역 스킬 설치
Codex에서 $shopl-sprint-planner로 직접 불러 쓰고 싶을 때 사용합니다.
npm install -g shopl-sprint-planner
shopl-sprint-planner --mode codex-skill기존 alias도 그대로 사용할 수 있습니다.
shopl-sprint-planner-skill --mode codex-skill다시 설치하거나 최신 설치 스크립트를 적용하고 싶을 때도 같은 npm 전역 설치 명령을 사용합니다.
npm install -g shopl-sprint-planner
shopl-sprint-planner --mode codex-skill커스텀 skills 경로로 설치
Codex 스킬 디렉터리를 직접 지정하고 싶다면 --target을 사용합니다.
npm install -g shopl-sprint-planner
shopl-sprint-planner --mode codex-skill --target /path/to/skills여기서 /path/to/skills는 "명령을 실행할 현재 폴더"가 아니라 "스킬 파일을 복사할 skills 루트 디렉터리"입니다.
예:
shopl-sprint-planner --mode codex-skill --target /Users/scott/tmp/my-skills실제 설치 경로:
/Users/scott/tmp/my-skills/shopl-sprint-planner설치 경로만 확인하려면:
shopl-sprint-planner --mode codex-skill --dry-run현재 폴더가 어디든 상관없고, 위 명령을 실행하면 Codex 전역 skills 경로에 설치됩니다.
2. Codex 프로젝트 규칙 설치
특정 프로젝트 루트에 AGENTS.md 블록을 추가해서 Codex가 그 저장소 안에서 Shopl 플래닝 규칙을 읽게 하고 싶을 때 사용합니다.
shopl-sprint-planner --mode codex-project --project-root /path/to/project현재 작업 중인 폴더를 프로젝트 루트로 쓰고 싶다면:
shopl-sprint-planner --mode codex-project --project-root .예:
shopl-sprint-planner --mode codex-project --project-root /Users/scott/work/my-repo생성/수정되는 파일:
/Users/scott/work/my-repo/AGENTS.md주의:
AGENTS.md는 프로젝트 규칙 파일이므로, Codex가 해당 저장소에서 작업할 때 항상 읽을 수 있습니다.- 다만 생성되는 블록 안에 "명시적으로 요청한 경우에만 사용" 규칙을 넣어두었습니다.
- 즉,
codex-skill모드처럼 전용 frontmatter 속성으로 막는 방식은 아니고, 프로젝트 규칙 텍스트로 제한하는 방식입니다.
3. Claude Code 전역 Skill 설치
Claude Code에서 어느 프로젝트를 열어도 /shopl-sprint-planner로 직접 불러 쓰고 싶을 때 사용합니다.
npm install -g shopl-sprint-planner
shopl-sprint-planner --mode claude-skill다시 설치하거나 최신 설치 스크립트를 적용하고 싶을 때도 같은 npm 전역 설치 명령을 사용합니다.
npm install -g shopl-sprint-planner
shopl-sprint-planner --mode claude-skill기본 설치 경로:
~/.claude/skills/shopl-sprint-planner/SKILL.mdCLAUDE_CONFIG_DIR 환경 변수를 쓰는 경우에는 아래 경로를 기준으로 설치합니다.
$CLAUDE_CONFIG_DIR/skills/shopl-sprint-planner/SKILL.md커스텀 Claude skills 경로로 설치
Claude Code skills 디렉터리를 직접 지정하고 싶다면 --target을 사용합니다.
shopl-sprint-planner --mode claude-skill --target /path/to/claude/skills실제 설치 경로:
/path/to/claude/skills/shopl-sprint-planner/SKILL.md설치 경로만 확인하려면:
shopl-sprint-planner --mode claude-skill --dry-run참고:
- 이 설치는 현재 사용자 계정의 Claude Code 환경 전체에 적용됩니다.
- 특정 프로젝트에만 한정되지 않습니다.
- 이미 Claude Code 세션이 실행 중일 때
~/.claude/skills디렉터리를 처음 만들었다면 Claude Code 재시작이 필요할 수 있습니다.
4. Claude Code 명령 설치
특정 프로젝트에서만 /shopl-sprint-planner라는 슬래시 명령으로 직접 실행하고 싶을 때 사용합니다.
shopl-sprint-planner --mode claude-command --project-root /path/to/project현재 작업 중인 폴더를 프로젝트 루트로 쓰고 싶다면:
shopl-sprint-planner --mode claude-command --project-root .생성되는 파일:
/path/to/project/.claude/commands/shopl-sprint-planner.md설치 후 Claude Code에서 다음처럼 사용합니다.
/shopl-sprint-planner이 방식은 프로젝트 안에 Claude Code 명령 파일을 같이 관리하고 싶을 때 적합합니다.
5. Claude Code 프로젝트 메모리 설치
Claude Code 프로젝트 메모리 파일 CLAUDE.md에 Shopl 플래닝 규칙 블록을 추가하고 싶을 때 사용합니다.
shopl-sprint-planner --mode claude-memory --project-root /path/to/project현재 작업 중인 폴더를 프로젝트 루트로 쓰고 싶다면:
shopl-sprint-planner --mode claude-memory --project-root .생성/수정되는 파일:
/path/to/project/CLAUDE.md주의:
CLAUDE.md는 프로젝트 메모리이므로 Claude Code가 해당 프로젝트에서 항상 읽을 수 있습니다.- 명시 호출 전용이 가장 중요하면
claude-memory보다claude-skill또는claude-command를 권장합니다.
6. 프로젝트용 묶음 설치
프로젝트 루트 하나를 기준으로 Codex용 AGENTS.md와 Claude Code용 .claude/commands를 한 번에 설치하려면:
shopl-sprint-planner --mode project --project-root /path/to/project현재 작업 중인 폴더에 바로 설치하려면:
shopl-sprint-planner --mode project --project-root .이 모드는 아래 두 파일을 만듭니다.
/path/to/project/AGENTS.md/path/to/project/.claude/commands/shopl-sprint-planner.md
즉:
- Codex는 프로젝트 규칙으로 인식
- Claude Code는 슬래시 명령으로 인식
설치 확인
Codex 전역 스킬 확인
ls ~/.codex/skills/shopl-sprint-planner예상 결과:
SKILL.mdagents/openai.yaml
Claude Code 설치 확인
전역 Skill 설치 확인:
ls ~/.claude/skills/shopl-sprint-planner예상 결과:
SKILL.md
프로젝트 명령 설치 확인:
ls /path/to/project/.claude/commands예상 결과:
shopl-sprint-planner.md
업데이트
스킬은 시작할 때 npm을 자동 조회하지 않습니다. 대신 현재 설치된 워크플로우 버전과 사용자가 터미널에서 직접 복사해 실행할 수 있는 확인/업데이트 명령을 보여줍니다.
Shopl Sprint Planner 현재 설치된 워크플로우 버전: 0.2.8
최신 버전 확인이나 업데이트가 필요하면 터미널에서 아래 명령을 직접 실행하세요.
현재 설치된 CLI 버전 확인:
shopl-sprint-planner --version
npm 최신 배포 버전 확인:
npm view shopl-sprint-planner version
현재 설치 방식으로 업데이트:
shopl-sprint-planner --update --mode codex-skill전역 설치한 패키지와 복사된 Codex/Claude 워크플로우 파일을 한 번에 갱신하려면 설치 방식에 맞는 --update 명령을 실행합니다.
shopl-sprint-planner --update --mode codex-skillClaude 전역 Skill, 프로젝트 규칙, 프로젝트 명령으로 설치한 경우에는 기존 설치 모드를 그대로 붙입니다.
shopl-sprint-planner --update --mode claude-skill
shopl-sprint-planner --update --mode project --project-root /path/to/project최신 배포 버전을 직접 확인하려면:
npm view shopl-sprint-planner version참고:
npm update -g shopl-sprint-planner만 실행하면 전역 패키지는 갱신되지만, 이미 복사된~/.codex/skills,~/.claude/skills, 또는 프로젝트 명령 파일은 갱신되지 않을 수 있습니다.shopl-sprint-planner --update ...는 최신 전역 패키지 설치 후 선택한 모드의 워크플로우 파일을 다시 씁니다.- 업데이트 후 새로 설치된 스킬 텍스트를 읽으려면 새 Codex 또는 Claude Code 세션이 필요할 수 있습니다.
- 예전
shopl-sprint-planner-0.1.0패키지를 설치했다면 한 번만 아래처럼 안정 패키지명으로 옮기면 됩니다.
npm uninstall -g shopl-sprint-planner-0.1.0
npm install -g shopl-sprint-planner
shopl-sprint-planner --mode codex-skill어떤 설치 방식을 써야 하나
추천 기준:
- Codex에서 정말 명시 호출 전용으로 쓰고 싶다
codex-skill
- 특정 프로젝트 안에서만 Codex 규칙으로 들고 가고 싶다
codex-project
- Claude Code에서 모든 프로젝트에 전역 Skill로 두고 싶다
claude-skill
- Claude Code에서 특정 프로젝트 명령처럼 직접 실행하고 싶다
claude-command
- Claude Code 프로젝트 메모리로 상시 규칙을 두고 싶다
claude-memory
- 한 프로젝트 루트에 Codex/Claude 둘 다 같이 깔고 싶다
project
npm 배포
배포는 태그 기반 GitHub Actions를 기본 경로로 사용합니다. npm publish만 단독 실행하는 배포는 하지 않습니다.
배포 전 필수 체크리스트:
package.json의version을 배포할 버전으로 올립니다.SKILL.md의 시작 안내 버전도 같은 버전으로 맞춥니다.CHANGELOG.md에## vX.Y.Z - YYYY-MM-DD릴리즈 노트를 추가합니다.npm run release:check를 실행해 패키징, 설치 dry-run, 릴리즈 노트 검증을 통과시킵니다.- 변경사항을 커밋합니다.
- 같은 버전의 태그를 만들고 푸시합니다.
npm run release:check
git tag -a v0.2.8 -m "Release v0.2.8"
git push origin main
git push origin v0.2.8태그가 푸시되면 .github/workflows/publish.yml이 실행되어 npm 배포를 진행하고, CHANGELOG.md의 해당 버전 내용을 사용해 GitHub Release를 생성하거나 갱신합니다.
응급 상황에서 로컬 수동 배포가 꼭 필요해도 릴리즈 노트와 태그는 생략하지 않습니다.
npm login
npm run release:check
npm publish
git tag -a v0.2.8 -m "Release v0.2.8"
git push origin main
git push origin v0.2.8위 태그 푸시가 GitHub Release 생성을 담당합니다. 이미 npm에 같은 버전이 올라가 있으면 workflow는 npm publish만 건너뛰고 GitHub Release는 계속 생성하거나 갱신합니다.
Trusted Publishing 설정
이 패키지는 GitHub Actions OIDC 기반 npm Trusted Publishing으로 배포합니다. 장기 publish token이나 NPM_TOKEN GitHub secret은 쓰지 않습니다.
1. npm 계정 2FA 활성화
npm Trusted Publishing 등록은 npm 계정 2FA가 켜져 있어야 가능합니다. npm 계정 Settings에서 2FA를 먼저 활성화합니다.
2. npm에 trusted publisher 등록
npx [email protected] trust github shopl-sprint-planner \
--repo Songgyubin/ShoplSprint \
--file publish.ymlnpm 웹에서 설정할 경우:
- npmjs.com에서
shopl-sprint-planner패키지 Settings로 이동 - Trusted publishing에서 GitHub Actions 선택
- Organization/User:
Songgyubin - Repository:
ShoplSprint - Workflow file:
publish.yml
참고:
npm trust명령은 npm 11.10.0 이상이 필요합니다.- 계정 2FA가 필요하며, 설정 중 npm 웹 인증이 열릴 수 있습니다.
- GitHub Actions trusted publishing은 GitHub-hosted runner에서 동작합니다.
package.json의repository.url은 GitHub 저장소와 일치해야 합니다.
3. 패키지 token publish 차단
trusted publisher 등록과 첫 배포 확인 후 npm 패키지 Settings > Publishing access에서 Require two-factor authentication and disallow tokens를 선택합니다. 이 설정은 기존 granular publish token을 통한 배포를 막지만, trusted publisher OIDC 배포는 계속 동작합니다.
4. 태그 기반 GitHub Actions 배포
git tag v0.2.8
git push origin v0.2.85. 수동 배포
로컬에서 직접 배포해야 하는 경우에는 계정 2FA로 로그인한 뒤 수동 publish를 실행합니다. 자동 배포에는 토큰을 쓰지 않습니다.
npm login
npm run release:check
npm publish참고
- 현재 패키지 이름은
shopl-sprint-planner입니다. - unscoped 패키지 이름은 npm 전체에서 유일해야 합니다.
publishConfig.access는public입니다.- 현재 패키지 라이선스는
UNLICENSED입니다.