Shopl Sprint Planner

Shopl 스프린트 플래닝 워크플로우를 Codex 또는 Claude Code에서 사용할 수 있게 설치하는 패키지입니다.

이 패키지는 한 가지 방식만 지원하지 않습니다. 사용하는 도구와 원하는 동작 방식에 따라 설치 모드를 나눠서 제공합니다.

설치 모드 요약

설치 모드는 터미널에 모드 이름만 입력하는 것이 아닙니다.

항상 아래처럼 설치 명령 + --mode 형태로 실행합니다.

npm install -g shopl-sprint-planner-0.1.0
shopl-sprint-planner --mode codex-skill

즉, codex-skill, codex-project, claude-command 같은 값은 "설치 프로그램이 어떤 방식으로 동작할지"를 고르는 옵션입니다.

| 모드 | 대상 | 설치 위치 | 호출 방식 | | --- | --- | --- | --- | | codex-skill | Codex | $CODEX_HOME/skills 또는 ~/.codex/skills | $shopl-sprint-planner 명시 호출 | | codex-project | Codex | 프로젝트 루트의 AGENTS.md | 프로젝트 규칙 파일 기반 | | 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-0.1.0
shopl-sprint-planner --mode codex-skill

일회성 실행만 하고 싶다면 npx도 사용할 수 있습니다.

npx shopl-sprint-planner-0.1.0 -- --mode codex-skill

이 명령은 아래 경로 중 하나에 스킬을 설치합니다.

• $CODEX_HOME/skills/shopl-sprint-planner
• CODEX_HOME이 없으면 ~/.codex/skills/shopl-sprint-planner

그다음 새 Codex 세션에서 아래처럼 명시적으로 호출해서 사용합니다.

$shopl-sprint-planner를 사용해서 Shopl 상위 Jira 티켓을 기준으로 필요한 질문을 한 번에 하나씩 진행하고, 필요하면 실제 하위 티켓을 먼저 만든 뒤 docs/work-plans 문서를 작성해줘.

참고:

• 이 설치는 현재 사용자 계정의 Codex 환경 전체에 적용됩니다.
• 특정 프로젝트에만 한정되지 않습니다.
• 이 스킬은 자동 참조용이 아니라 명시 호출 전용으로 설정되어 있습니다.

1. Codex 전역 스킬 설치

Codex에서 $shopl-sprint-planner로 직접 불러 쓰고 싶을 때 사용합니다.

npm install -g shopl-sprint-planner-0.1.0
shopl-sprint-planner --mode codex-skill

기존 alias도 그대로 사용할 수 있습니다.

shopl-sprint-planner-skill --mode codex-skill

일회성 실행만 하려면:

npx shopl-sprint-planner-0.1.0 -- --mode codex-skill

커스텀 skills 경로로 설치

Codex 스킬 디렉터리를 직접 지정하고 싶다면 --target을 사용합니다.

npm install -g shopl-sprint-planner-0.1.0
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 명령 설치

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 쪽에서 가장 명시 호출 전용에 가깝습니다.

4. 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-command를 권장합니다.

5. 프로젝트용 묶음 설치

프로젝트 루트 하나를 기준으로 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.md
• agents/openai.yaml

Claude 명령 확인

ls /path/to/project/.claude/commands

예상 결과:

• shopl-sprint-planner.md

어떤 설치 방식을 써야 하나

추천 기준:

1. Codex에서 정말 명시 호출 전용으로 쓰고 싶다
   • codex-skill
2. 특정 프로젝트 안에서만 Codex 규칙으로 들고 가고 싶다
   • codex-project
3. Claude Code에서 명령처럼 직접 실행하고 싶다
   • claude-command
4. Claude Code 프로젝트 메모리로 상시 규칙을 두고 싶다
   • claude-memory
5. 한 프로젝트 루트에 Codex/Claude 둘 다 같이 깔고 싶다
   • project

npm 배포

처음 수동 배포:

npm login
npm run release:check
npm publish

GitHub Actions 배포:

1. 저장소 secret에 NPM_TOKEN 추가
2. v0.1.0 같은 태그 푸시
3. .github/workflows/publish.yml에서 검증 후 배포

웹 없이 지속 배포하기

1. CLI에서 publish token 생성

npx [email protected] token create \
  --name "shopl-sprint-planner-publish" \
  --token-description "shopl-sprint-planner publish" \
  --packages shopl-sprint-planner-0.1.0 \
  --packages-and-scopes-permission read-write \
  --bypass-2fa=true

로컬 npm이 granular token 생성을 지원하면 아래 명령도 가능합니다.

npm token create \
  --name "shopl-sprint-planner-publish" \
  --token-description "shopl-sprint-planner publish" \
  --packages shopl-sprint-planner-0.1.0 \
  --packages-and-scopes-permission read-write \
  --bypass-2fa=true

참고:

• 토큰 생성 중 npm 비밀번호와 이메일 OTP를 물을 수 있습니다.
• 이 과정은 최초 1회 설정용입니다.
• 이 저장소를 작업한 환경에서는 npm 11.6.2가 granular token 플래그를 인식하지 못해서 npx [email protected] ... 명령을 쓰는 편이 더 안전했습니다.

2. 셸에 토큰 넣기

export NPM_TOKEN="paste-the-token-here"

3. 로컬과 GitHub Actions에 토큰 저장

npm run setup:publish-token -- --gh-secret

dry-run:

npm run setup:publish-token -- --gh-secret --dry-run

4. 계속 배포하기

로컬에서 바로 배포:

npm publish

태그 기반 GitHub Actions 배포:

git tag v0.1.0
git push origin v0.1.0

참고

• 현재 패키지 이름은 shopl-sprint-planner-0.1.0입니다.
• unscoped 패키지 이름은 npm 전체에서 유일해야 합니다.
• publishConfig.access는 public입니다.
• 현재 패키지 라이선스는 UNLICENSED입니다.