Codexharness v2 Full

이 패키지는 기존 프로젝트에 Codex 작업환경을 넣어주는 공식 설치 배포본입니다.

한 줄로 말하면:

• 내 프로젝트 코드는 그대로 두고
• Codex가 더 잘 일하도록 필요한 재료를 넣고
• graphify, agnix, pre-commit, rtk까지 바로 쓸 수 있게 준비해줍니다

가장 쉬운 설치

npx @kenda0988/codexharness-v2-full --target /path/to/your-repo

설치가 끝나면 보통 바로 이런 상태가 됩니다.

• Codex가 프로젝트 안 규칙과 스킬을 읽을 수 있음
• 코드 구조를 보는 Graphify가 켜져 있음
• 커밋 전에 한 번 더 검사하는 안전장치가 붙어 있음
• Codex가 터미널 명령을 더 효율적으로 쓰도록 RTK가 연결됨

설치하면 실제로 무엇이 생기나

설치 후에는 크게 세 가지가 준비됩니다.

1. 프로젝트 안에 들어가는 것

프로젝트 안에는 Codex가 읽는 작업 재료가 들어갑니다.

• AGENTS.md
• .codex/
• .agents/skills/
• upstreams/ecc
• upstreams/superpowers
• overlays/ecc-codex-extras
• overlays/superpowers-codex-runtime
• docs/code_review.md

쉽게 말하면, Codex가 이 프로젝트에서 어떤 방식으로 일해야 하는지 바로 이해할 수 있는 기본 세트가 들어옵니다.

2. Graphify 코드 지도

이 설치기는 파일만 복사하고 끝나지 않습니다.

현재 기준으로는:

• graphify CLI가 있는지 확인하고
• 버전이 맞으면 재설치하지 않고 그대로 쓰고
• 없거나 버전이 다르면 잠긴 버전으로 설치하고
• 그 뒤 해당 프로젝트에만 Graphify 세팅을 붙입니다

여기서 “세팅”은 두 가지입니다.

• graphify hook install
• 해당 프로젝트 폴더에서 graphify . --watch 실행

중요한 점은 --watch가 전역으로 모든 폴더를 감시하는 게 아니라, 설치 대상 프로젝트 하나에만 붙는다는 점입니다.

3. 컴퓨터 쪽 준비

프로젝트 안 설정만 바꾸는 게 아니라, 컴퓨터 쪽도 같이 준비합니다.

• graphify CLI
• agnix CLI
• pre-commit CLI
• rtk CLI
• Codex global instructions에 RTK 연결

즉 설치가 끝나면 “이 프로젝트는 바로 Codex 친화적으로 움직이기 시작하고”, “필요한 보조 도구도 같이 준비된 상태”가 됩니다.

설치 직후에 사용자는 뭘 하면 되나

비개발자 기준으로는 이 순서면 충분합니다.

1. 프로젝트를 Codex에서 다시 엽니다.
2. 새 스레드를 시작합니다.
3. graphify-out/GRAPH_REPORT.md가 생기는지 봅니다.
4. Codex에게 그냥 평소처럼 작업을 요청합니다.

큰 기능을 만들 때는 이런 스킬 이름을 직접 말해도 좋습니다.

• brainstorming
• writing-plans
• systematic-debugging
• verification-before-completion

각 도구를 쉬운 말로 설명하면

Graphify

Graphify는 코드 지도를 만들어주는 도구입니다.

Codex가 파일을 무작정 뒤지는 대신:

• 전체 구조를 먼저 보고
• 중요한 파일을 좁혀서 들어가고
• 코드가 바뀌면 hook과 watch가 그래프를 다시 맞춥니다

즉 “이 프로젝트가 어떻게 생겼는지 먼저 이해하게 해주는 층”이라고 보면 됩니다.

Superpowers

Superpowers는 “어떤 순서로 일할지”를 잡아주는 스킬 묶음입니다.

예를 들면:

• 일이 크면 먼저 brainstorming
• 설계를 작업 단계로 나누려면 writing-plans
• 디버깅이 꼬이면 systematic-debugging

즉 더 화려한 답변을 만드는 도구라기보다, 더 안정적인 작업 흐름을 만드는 쪽에 가깝습니다.

ECC

ECC는 Codex의 기본 코딩 습관을 더 좋게 만드는 바탕입니다.

사용자는 보통 이런 식으로 체감합니다.

• 테스트와 검증을 더 챙김
• 리뷰 관점을 더 자주 챙김
• 성급하게 바로 구현만 하려는 흐름을 줄임

Agnix

Agnix는 설정 파일이 망가지지 않았는지 검사하는 안전장치입니다.

평소에는 신경 쓸 일이 거의 없습니다. Codex가 관련 설정을 바꾸면 뒤에서 확인하고, 문제가 있으면 짧게 알려줍니다.

RTK

RTK는 터미널 명령을 더 짧고 효율적으로 쓰게 돕는 도구입니다.

직접 이렇게 쓸 수도 있습니다.

rtk git status
rtk npm test
rtk pytest -q

하지만 더 자주 느끼는 건, Codex가 shell 작업을 할 때 RTK 친화적으로 움직인다는 점입니다.

pre-commit

pre-commit은 커밋 직전에 마지막으로 한 번 더 잡아주는 검사기입니다.

쉽게 말하면:

• 실수한 설정 파일
• 깨진 JSON/TOML/YAML
• 기본적인 포맷 문제

같은 걸 Git에 올리기 전에 한 번 더 막아줍니다.

설치 후 폴더를 어떻게 보면 되나

설치가 끝나면 프로젝트는 대략 이렇게 보입니다.

my-project/
├─ AGENTS.md
├─ .codex/
├─ .agents/skills/
├─ graphify-out/
├─ docs/
├─ upstreams/
├─ overlays/
└─ 실제 프로젝트 코드

비개발자 기준으로는 이렇게 이해하면 쉽습니다.

• AGENTS.md Codex가 이 프로젝트에서 따라야 하는 기본 안내판입니다.
• .agents/skills/ Codex가 일하는 방식을 배우는 스킬 모음입니다.
• .codex/ Codex가 실제로 읽는 설정 폴더입니다.
• graphify-out/ 코드 구조 요약과 그래프 산출물이 쌓이는 곳입니다.
• docs/ 설계, 계획, 운영 문서가 쌓이는 곳입니다.
• upstreams/ 원본 스냅샷 보관소입니다.
• overlays/ 우리 쪽에서 덧붙인 연결 레이어입니다.

지금 헷갈리면 이것만 보면 된다

• 코드 구조가 궁금하면 graphify-out/GRAPH_REPORT.md
• 왜 자꾸 설계부터 하려는지 궁금하면 Superpowers
• 왜 테스트와 리뷰를 챙기는지 궁금하면 ECC
• 설치/운영 방법이 궁금하면 docs/runbooks/

아주 짧게 요약하면:

• Graphify는 코드 구조를 먼저 잡아줍니다
• Superpowers는 일하는 순서를 잡아줍니다
• ECC는 품질 기준을 잡아줍니다

설치 옵션

실제로 바꾸기 전에 예정 작업만 보고 싶으면:

npx @kenda0988/codexharness-v2-full --target /path/to/your-repo --dry-run

결과를 파일로 남기고 싶으면:

npx @kenda0988/codexharness-v2-full \
  --target /path/to/your-repo \
  --dry-run \
  --report-json /tmp/codexharness-report.json

컴퓨터 전체 도구 설치를 건너뛰고 repo 파일만 넣고 싶으면:

npx @kenda0988/codexharness-v2-full \
  --target /path/to/your-repo \
  --skip-machine-bootstrap

이 옵션을 쓰면 graphify, rtk, agnix, pre-commit 같은 전역 도구 준비는 건너뛰고, 프로젝트 안 파일만 설치합니다.

유지보수자 메모

일반 사용자는 자주 볼 필요 없지만, 배포를 관리하는 사람은 이 부분만 알면 됩니다.

• source of truth는 Codexharness_v2 레포입니다
• full 배포 레포는 source 레포에서 sync해서 만듭니다
• full 레포에서는 npm test로 smoke test를 돌립니다
• 배포는 GitHub Actions 기반입니다

현재 기준 publish 흐름은:

1. source 레포 수정
2. source 레포 테스트
3. scripts/prepare-full-distribution.py로 full 레포 sync
4. full 레포 npm test
5. push 후 배포

이 레포는 npm Trusted Publisher 기준으로 배포할 수 있게 설계되어 있습니다. 즉 GitHub Release 또는 publish workflow를 통해 배포하고, 로컬 OTP 없이 진행하는 흐름을 기본으로 둡니다.

README에서 기억할 키워드는 이것뿐입니다.

• Trusted Publisher
• GitHub Release
• OTP 없이

주의

• 같은 경로에 다른 내용이 있으면 installer는 조용히 덮어쓰지 않고 멈춥니다.
• graphify . --watch는 설치 대상 프로젝트 하나에만 붙습니다.
• upstreams/는 평소 작업 폴더라기보다 원본 참고 스냅샷입니다.
• overlays/ecc-codex-extras는 ECC를 대체하는 포크가 아니라 Codex 전용 보강 레이어입니다.