SeoKang Codex 스킬

설치와 기준 저장소

• 배포 패키지: seokang-sk
• 설치 명령: sk setup
• 수정 가능한 원본 저장소: ~/.agents/skills
• 동기화 대상 Codex 런타임: ~/.codex

핵심 규칙은 단순하다.

sk는 최종적으로 ~/.agents/skills의 로컬 저장소를 기준으로 동작해야 한다.

즉, npm으로 배포한 뒤에도 ~/.agents/skills/skills/sk-feature-workflow/SKILL.md 같은 스킬 파일을 로컬에서 바로 수정할 수 있어야 한다. 배포 패키지는 설치 진입점과 디스패치만 담당하고, 실제 기준 원본은 로컬 저장소에 남는다.

중요:

• ~/.agents/skills는 이 저장소의 repo root다.
• 실제 skill 폴더는 ~/.agents/skills/skills/ 아래에 둔다.
• docs/, codex-config/, scripts/는 지원 폴더이고, skills/가 skill 묶음 폴더다.

30초 구조 요약

• repo root는 ~/.agents/skills다.
• 실제 skill은 ~/.agents/skills/skills/sk-이름/SKILL.md 형태로 둔다.
• docs/, codex-config/, scripts/는 지원 폴더이며, skills/만 skill 묶음 폴더다.

처음 설치

npm install -g seokang-sk
sk setup
cd /path/to/project
sk init
sk status

• DB safe-read login-path alias를 프로젝트 track 기준으로 맞추려면 아래 명령을 사용한다.

sk setup --configure-db-safe-read

• Notion 문서까지 함께 쓸 계획이면 설치 후 한 번 더 아래 명령을 실행한다.

sk setup --configure-notion

• Records / Projects 데이터베이스 URL에 Notion id가 들어 있으면 data source id는 setup 중 자동으로 추출한다.

• Notion 문서 기록이 invalid_grant, unauthorized, forbidden 같은 인증 오류로 실패하면 아래 명령으로 MCP 인증을 다시 연결한다.

• Tool ... not found처럼 특정 Notion tool만 빠진 경우는 로그인 문제가 아닐 수 있으니, exact error를 남기고 남아 있는 Notion MCP tool로 우회 가능한지 먼저 확인한다.

• notion-query-data-sources / query_data_sources는 더 이상 Notion 기록의 1차 탐색 경로로 두지 않는다.

• local config에 data source id가 있으면 fetch / create_pages / update_page를 먼저 쓰고, lookup이 필요할 때만 search -> fetch 순서로 보완한다.

codex mcp login notion

자세한 구조 문서:

• docs/sk-setup-architecture.md
• docs/sk-cli-guide.md
• docs/sk-notion-workspace.md

자동화 기준 문서:

• docs/automations/server-log-check.md
• docs/automations/daily-thread-retrospective.md

이 저장소는 SeoKang 개인 개발 워크플로를 Codex Skill과 공용 Codex 데스크톱 설정 원본으로 관리하기 위한 저장소다.

기능 개발, 버그 수정, 리팩토링, 기획, 배포뿐 아니라 문서화와 Notion 기록까지 포함한 작업 방식을 정리한다.

디렉터리 구조

.
|- skills/
|  |- sk-feature-workflow  # 기능 작업 메인 오케스트레이터
|  |- sk-bugfix-workflow   # 버그 수정 워크플로
|  |- sk-refactor          # 리팩토링 워크플로
|  |- sk-plan              # 기획/설계 응답 워크플로
|  |- sk-db                # DB 변경 워크플로
|  |- sk-design-system     # 디자인 시스템 점검/구축
|  |- sk-docs              # 변경 문서 작성
|  |- sk-git               # git add/commit/push 워크플로
|  |- sk-deploy            # 배포 워크플로
|- codex-config/
|  |- config/              # ~/.codex/config.toml 공용 원본
|  |- agents/              # ~/.codex/agents 공용 원본
|  |- rules/               # ~/.codex/rules 공용 원본
|- templates/
|  |- agent/               # 프로젝트용 AGENT.MD bootstrap 템플릿
|- scripts/                # 공용 설치 / 보조 스크립트

• 실제 skill 엔트리는 skills/sk-*/SKILL.md다.

어디를 수정하나

• skill 동작 변경: skills/sk-*/SKILL.md
• 설치/런타임 설정 변경: codex-config/**, scripts/**
• 프로젝트용 AGENT.MD 기본 틀 변경: templates/agent/*.md
• 사용법/운영 가이드 변경: docs/**, README.MD

목적

• 기능/버그/리팩터링 작업을 명확히 분리한다.
• 코드 변경뿐 아니라 문서와 기록까지 같은 규칙으로 관리한다.
• 회사 맥북, 집 윈도우처럼 데스크톱이 달라도 같은 Codex 셋업을 재현한다.
• 반복되는 Codex 설정 수정을 로컬 수작업이 아니라 저장소 원본 기준으로 동기화한다.

실행 방식

• sk는 별도 앱 UI가 아니라 CLI 명령으로만 동작한다.
• sk setup이 sync하는 대상은 ~/.codex이고, sk init은 현재 프로젝트의 .sk/ 상태를 준비한다. 필요하면 --agent-md로 프로젝트 루트 AGENT.MD도 함께 만든다.
• 옵션과 예시는 sk help, sk help <command>, <command> --help로 바로 확인한다. 예: sk help init, sk init --help
• OMX가 omx setup처럼 짧아 보이는 이유는 npm 전역 CLI로 설치되기 때문이다.
• 지금 sk도 최초 1회만 npm link로 등록하면 이후에는 sk setup, sk init만 기억하면 된다.
• 실행 전제:
  • Node.js 20+
  • Windows는 Git Bash 권장

저장소를 직접 개발할 때

• 최초 1회만 이 저장소에서 전역 CLI를 등록한다.

cd /c/Users/<user>/.agents/skills
npm link

• 그 다음부터는 어디서든 이 세 줄이면 된다.

sk setup
sk init
sk check
sk status

• Notion 기록을 쓸 계획이면 최초 1회는 아래처럼 사용자별 Notion 위치도 같이 설정한다.

sk setup --configure-notion

• 다른 프로젝트를 바로 지정하고 싶으면 init, status, memory 계열에 --cwd를 붙이면 된다.
  • sk init --cwd /path/to/project
  • sk status --cwd /path/to/project
• npm link 없이도 저장소 안에서는 fallback으로 sh ./sk setup을 계속 쓸 수 있다.
• sk 사용 흐름 설명은 docs/sk-cli-guide.md를 기준 문서로 본다.

첫 설치 예제

권장 새 PC 흐름:

1. Codex 설치
2. npm install -g seokang-sk
3. sk setup
4. 작업할 프로젝트 루트에서 sk init
5. sk check
6. 필요하면 sk status

Windows Git Bash

sk setup
cd /c/path/to/project
sk init
sk check
sk status

macOS / Linux

sk setup
cd /path/to/project
sk init
sk check
sk status

저장소 로컬 fallback 예제

cd /c/Users/<user>/.agents/skills
sh ./sk setup
sh ./sk check
sh ./sk status

주요 워크플로

• sk-feature: 기능 구현 작업의 기본 진입점
• sk-bugfix: 근거 기반 버그 수정
• sk-refactor: 기능 변경 없는 구조 개선
• sk-plan: 기획/설계 응답
• sk-git: 변경 파일 기준 commit/push
• sk-deploy: 서버/NAS 배포와 npm publish 배포

새 스레드 시작 규칙

• sk-feature, sk-bugfix, sk-refactor, sk-plan으로 새 스레드를 시작할 때는 바로 수정/설계에 들어가지 않고 최근 맥락을 먼저 읽는다.
• 기본 순서:
  • 최근 7일 git history 확인 (git log --since='7 days ago')
  • repo 루트 README*
  • docs/** 인덱스/개요 문서
  • 현재 요청과 직접 관련된 상세 문서
• 문서가 많으면 전부 읽으려 하지 말고, 인덱스/개요 → 관련 상세 순서로 좁혀 읽는다.
• .agents/skills에서는 README.MD, docs/**, skills/**, 수정 대상 SKILL.md, 관련 setup/config 문서를 기본 세트로 본다.

Codex 설정 공유

이 저장소는 skill만 관리하는 것이 아니라 Codex 데스크톱 설정도 공용 원본으로 관리한다.

공용 원본:

• codex-config/config/shared-config.toml
• codex-config/config/windows-config.toml
• codex-config/agents/seokang/*.toml
• codex-config/rules/skills-shared.rules

설치 결과:

• ~/.codex/config.toml은 codex-config/config/* 원본을 기반으로 생성된다.
• ~/.codex/agents/seokang/*.toml은 저장소 원본을 기반으로 동기화된다.
• ~/.codex/rules/skills-shared.rules는 저장소 원본을 그대로 복사한다.
• ~/.codex/sk/notion/workspace.json은 사용자별 Notion workspace 설정 파일이다.
• setup 중 기존 대상 파일이 바뀌면 현재 작업 디렉터리의 .sk/backups/setup/** 아래에 백업을 남긴다.
• 공용 기본값은 approval_policy = "never", sandbox_mode = "danger-full-access"다.
• 현재 설정은 Playwright MCP 승인창이 workspace-write + never에서도 계속 나타나는 현상을 확인한 뒤, danger-full-access + never까지 실험해 보기 위한 강한 기본값이다.
• CLI로 쓰면 codex --sandbox danger-full-access -a never와 같은 기준이다.
• shared subagent를 실제로 사용할 수 있도록 공용 source에서 multi_agent feature를 켠다.

설치 명령:

sh ~/.agents/skills/scripts/install_codex_shared_setup.sh

sh /c/Users/<user>/.agents/skills/scripts/install_codex_shared_setup.sh

새 CLI 명령:

sk setup

sk init

sk check

sk status

sk memory show

sk search "reviewer"

호환성:

• 기준 설치 스크립트는 scripts/install_codex_shared_setup.sh 하나다.
• 전역 CLI 등록을 원하면 이 저장소 루트에서 최초 1회 npm link를 실행한다.
• Windows에서도 Git Bash 환경에서 동일한 .sh를 실행한다.
• Windows에서 sh 명령이 없으면 Git for Windows(Git Bash)를 설치한 뒤 다시 실행한다.
• Windows PowerShell에서 실행 정책 때문에 sk.ps1이 막히면 sk.cmd를 쓰거나 생성된 sk.ps1을 비활성화해 sk.cmd가 우선 잡히게 한다.
• 기존 scripts/install_codex_shared_rules.sh는 새 설치 스크립트를 호출하는 래퍼로 유지한다.
• scripts/sk.sh는 Node 기반 scripts/sk.mjs를 호출하는 Git Bash 표준 진입점이다.
• repo 루트 ./sk는 npm link를 쓰지 않을 때의 fallback 진입점이다.
• 다른 프로젝트를 지정해야 하면 대부분의 명령에서 --cwd /path/to/project를 같이 쓰면 된다.
• sk setup이 설치와 동기화를 맡는다.
• sk init이 프로젝트 상태 준비를 맡는다.

상태 디렉터리:

• sk init은 현재 작업 디렉터리 아래 .sk/를 만들고, --agent-md를 붙이면 프로젝트 루트 AGENT.MD도 함께 만든다.
• sk setup은 관리용 저장소 ~/.agents/skills/.sk/를 setup 상태/백업 기준 경로로 사용한다.
• .sk/setup-scope.json: 마지막 init/setup 기록
• .sk/project-memory.json: 다음 세션이 읽을 구조화 메모
• .sk/notepad.md: 우선 컨텍스트/작업 메모
• .sk/backups/setup/**: setup 중 덮어쓰기 전에 남긴 백업
• Notion workspace 설정은 ~/.codex/sk/notion/workspace.json을 쓴다.

중요 제한:

• skills-shared.rules는 shell prefix 자동 허용만 처리한다.
• Notion/Figma/Playwright 같은 MCP/tool 승인 정책은 shared-config.toml에서 함께 관리한다.
• 공용 subagent 등록은 shared-config.toml의 [agents.*]와 codex-config/agents/seokang/*.toml에서 함께 관리한다.
• danger-full-access는 workspace 밖 파일, 홈 디렉터리, SSH, 네트워크, 외부 명령 실행까지 sandbox 제한 없이 진행할 수 있게 한다.
• approval_policy = "never"라서 승인창도 띄우지 않는다.
• 기본 분석용 공용 subagent는 read-only sandbox를 기본으로 하며, Notion MCP와 Playwright는 agent 파일에서 명시적으로 비활성화한다.
• 브라우저 재현, 콘솔/네트워크 증거, Notion 조회/기록은 전용 tool subagent를 두지 않고 메인 agent가 직접 수행한다.
• Notion 관련 조회/기록은 MCP 우선을 기본으로 한다. 인증/권한 실패가 나면 exact error를 먼저 보고한다.
• Notion 실패를 숨기기 위해 Playwright로 notion.so를 기본 경로처럼 사용하지 않는다. 웹 UI fallback은 사용자가 명시적으로 요청한 경우에만 허용한다.
• 같은 설정은 Playwright만이 아니라 현재 세션 전체에 적용된다.
• 이 설정은 보안 유지형이 아니라 실험/자동화 우선 설정이다.
• 현재 데스크톱 빌드 기준으로도 Playwright MCP 승인창 제거는 보장되지 않으므로, 실제 효과는 새 세션에서 직접 확인해야 한다.

다른 프로젝트에도 프로젝트별 rules가 필요하면 각 프로젝트 루트의 .codex/rules/*.rules에 별도로 추가해서 관리한다.

배포

sk-deploy는 로컬에서 빌드한 결과물을 배포 대상으로 올리는 워크플로다.

• 일반 서버 프로젝트: 원격 서버/NAS 업로드 + 재시작
• .agents/skills 같은 seokang-skill 프로젝트: npm publish

예시 설정 파일:

REMOTE_HOST=your-host
REMOTE_PORT=your-port
REMOTE_USER=your-user
REMOTE_DIR=/opt/km-admin-api
JAR_NAME=km-admin-api.jar
LOCAL_JAR_PATH=./build/libs/km-admin-api.jar

seokang-skill 프로젝트에서는 아래 스크립트/템플릿을 사용한다.

• skills/sk-deploy/deploy-npm.sh
• skills/sk-deploy/deploy.local.conf.template.npm

커밋 메시지 규칙

• feat: 기능 추가
• fix: 버그 수정
• refactor: 구조 개선
• deploy: 배포

안전 원칙

• 추정 기반 구현 금지
• API 계약 변경 시 전체 이름/응답 구조 확인
• 리팩터링은 동작 유지가 전제
• build 성공과 정상 동작은 별개로 본다
• Notion 기록을 임의로 생략하지 않는다

설치 스크립트 사용법

• 이 설치 스크립트는 이 저장소의 공용 Codex 설정을 로컬 ~/.codex로 한 번에 복사/동기화한다.
• 같은 설치 스크립트가 공용 subagent도 ~/.codex/agents/seokang으로 함께 동기화한다.
• 내부적으로는 scripts/sk.mjs setup 흐름을 호출한다.
• macOS shell 설치 예시: sh ~/.agents/skills/scripts/install_codex_shared_setup.sh
• Windows Git Bash shell 설치 예시: sh /c/Users/<user>/.agents/skills/scripts/install_codex_shared_setup.sh
• 이 저장소의 공용 Codex 설정이 바뀌면 같은 설치 스크립트를 다시 실행한다.
• 로컬 대상 파일이 source와 다르면 설치 스크립트가 덮어쓰기 전에 .sk/backups/setup/** 아래에 백업을 남긴다.
• Windows에서 sh를 인식하지 못하면 Git for Windows(Git Bash)를 설치한 뒤 같은 .sh 명령을 다시 실행한다.

sk 명령

• setup
  • ~/.agents/skills 저장소를 준비하거나 재사용하고, config/rules/shared agents를 sync한 뒤 check까지 실행한다.
  • 최초 setup 시 interactive 환경이면 사용자별 Notion workspace 설정 파일도 함께 만들 수 있다.
  • --dry-run, --verbose, --configure-notion, --skip-notion을 지원한다.
• init
  • 현재 프로젝트 루트의 .sk/ 상태 파일을 준비한다.
  • --agent-md를 붙이면 프로젝트 루트에 AGENT.MD 초안도 함께 만든다.
  • --cwd <path>, --agent-md, --dry-run, --force, --verbose를 지원한다.
• check
  • 현재 설치가 source와 일치하는지 확인한다.
  • Notion workspace 설정 파일 존재 여부와 필수 필드도 함께 확인한다.
  • --cwd <path>, --json을 지원한다.
• status
  • 현재 .sk 상태, memory/notepad, Notion workspace 설정 상태, 최근 backup, check 결과를 함께 보여준다.
  • --cwd <path>, --json을 지원한다.
• memory
  • .sk/project-memory.json과 .sk/notepad.md를 초기화하고 읽는다.
  • show, init, add-note, add-directive를 지원한다.
• search
  • 로컬 Codex transcript에서 기존 세션 내용을 검색한다.
  • --since, --project, --session, --limit, --case-sensitive, --json을 지원한다.

공용 하위 에이전트

• 공용 subagent 등록은 codex-config/config/shared-config.toml에서 관리한다.
• agent별 동작은 codex-config/agents/seokang/*.toml에서 관리한다.
• 현재 공용 세트는 다음과 같다:
  • context_mapper
  • spec_clarifier
  • reviewer
  • docs_researcher
  • codex_improver
  • api_flow_mapper
  • db_impact_reviewer
  • ui_flow_mapper
  • design_checker
• 설정과 유지보수 방법은 docs/codex-subagents.md에 정리했다.
• sk-feature, sk-bugfix, sk-db는 shared subagent가 설치되어 있으면 사용자가 따로 지시하지 않아도 내부적으로 dispatch할 수 있도록 설계한다.
• 기본 분석용 subagent는 Notion MCP와 Playwright를 직접 사용하지 않고, 이런 tool 작업은 메인 agent가 맡는다.

프로젝트 AGENT.MD

• AGENT.MD는 프로젝트별 고정 규칙 문서다.
• README는 사람용 개요/설치 문서, .sk/*는 세션 메모, AGENT.MD는 agent가 먼저 읽어야 할 프로젝트 계약서로 분리해서 쓴다.
• 성능 차이가 크지 않은 한 기본 초안은 한글로 생성하고, 명령어/식별자/경로만 원문을 유지한다.
• 새 프로젝트에서 바로 만들려면 아래처럼 시작한다.

sk init --agent-md

• 다른 프로젝트를 미리 준비할 때는 아래처럼 쓴다.

sk init --cwd /path/to/project --agent-md

• 기본 템플릿 원본은 templates/agent/base.md, templates/agent/frontend.md, templates/agent/backend.md, templates/agent/codex.md다.

작성자

SeoKang 작성