[📚정보] 바이브 코딩 입문 가이드

[사가다자(choice2234)]

요약

1. 일단 코덱스를 깔아

2. AGENTS.md을 써

3. 코드 요약 문서를 만들어

4. 명령을 대충 내리지 마

1. 일단 코덱스를 깔아

여기서 일단 코덱스를 까셈

클로드 코드? VS코드? 안티그래비티? 그런 거 다 별로임 입문자한테는 코덱스가 짱이야

깔았으면 일단 실행해서 대충 다음다음확인다음확인 눌러서 기본 설정 완료하셈

그럼 대충 이런 화면이 뜰 거임

여기서 일단 멈춰

파일 탐색기로 들어가서 "상위 폴더 이름에 한글이 없는 폴더 1개"를 만들어 (나는 대충 "game1"이라는 폴더를 만들었다고 칠게)

그리고 game1 폴더 안에 "AGENTS.md"라는 파일을 만들어

AGENTS.md이 뭐냐하면, "AI가 모든 문서 중에 가장 먼저 읽을 문서"임

여기다가 AI가 조심해야 하는 거 꼭 지켜야하는 거 등등 다 때려박으면 됨

일단 폴더랑 파일 만들었으면 다시 코덱스로 돌아오셈

그리고 화면 가운데에 "프로젝트에서 작업하기" 부분을 눌러서 "새 프로젝트 추가"로 game1 폴더를 추가하셈

이제 기본 세팅은 끝났음

2. AGENTS.md을 써

그래서 AGENTS.md을 어떻게 쓰냐?

그냥 파일 탐색기에서 해당 파일 열어서 AI 지침같은 거 알아서 적으면 됨

모르는 거 있으면 코덱스한테 "이 폴더에 있는 AGENTS.md를 바이브 코딩에 적합하게 작성하고 싶은데 어떻게 할까?"라고 물어보셈

근데 귀찮잖아?

그래서 내가 쓰는 AGENTS.md 양식을 줄 테니 (cc0로 사용하셈) 그냥 복붙하셈

필요하면 수정해서 사용하고 ㅇㅇ

# AI 바이브 코딩 규칙

이 프로젝트는 FHD 가상 해상도 기반 웹 게임입니다. 코드를 수정할 때는 먼저 수정할 파일을 좁히고, 작은 단위로 바꾸는 것을 기본 흐름으로 합니다.

## 1. 작업 시작 순서

*   **먼저 `CODE_SUMMARY.md`를 확인하세요.** 변수, 함수, 클래스, 파일 책임을 찾을 때 전체 파일을 훑기 전에 `CODE_SUMMARY.md`의 파일 맵과 함수 요약을 먼저 봅니다.

*   **수정할 파일을 1~3개로 좁히세요.** 기능이 여러 영역에 걸리더라도 먼저 핵심 책임 파일을 찾고, 필요한 경우에만 인접 파일을 엽니다.

*   **큰 파일을 다시 키우지 마세요.** 새 기능이 길어질 경우 기존 책임에 맞는 작은 파일을 추가하거나, 이미 분리된 파일에만 붙입니다.

*   **수정 후 요약 문서를 갱신하세요.** 새 전역 변수, 클래스 프로퍼티, 핵심 함수, 이벤트 흐름, 파일 책임이 바뀌면 `CODE_SUMMARY.md`를 함께 갱신합니다.

## 2. FHD 가상 해상도 원칙

*   **좌표계는 항상 1920x1080 기준입니다.** 화면 배치, 이동, 충돌 처리는 `window.innerWidth`, `clientWidth`가 아니라 `GAME_WIDTH(1920)`와 `GAME_HEIGHT(1080)` 기준으로 계산합니다.

*   **입력 좌표는 반드시 변환합니다.** 마우스/터치 이벤트의 브라우저 좌표를 직접 쓰지 말고 `getVirtualCoordinates`를 거친 FHD 가상 좌표만 게임 로직에 전달합니다.

*   **렌더링은 스케일링된 컨텍스트 안에서 합니다.** 캔버스 물리 크기는 `devicePixelRatio`에 맞춰 바뀌며, 그리기는 `ctx.setTransform()`으로 맞춰진 1920x1080 좌표계 안에서 수행된다고 가정합니다.

## 3. 게임 루프 원칙

*   **상태 변경은 `update(deltaTime)`에서만 합니다.** 좌표 이동, 낙하, 충돌, 수명 감소, 배열 제거 같은 상태 변화는 `update` 또는 입력 이벤트 핸들러에서 처리합니다.

*   **`draw()`는 그리기만 합니다.** `draw`와 하위 렌더링 함수에서 객체의 `x`, `y`, 상태값, 배열 내용을 바꾸지 않습니다.

*   **시간 기반 이동에는 `deltaTime`을 씁니다.** 모니터 주사율과 기기 성능에 따라 속도가 바뀌지 않도록 `x += speed * (deltaTime / 1000)` 형태를 사용합니다.

## 4. 기능 추가와 수정 규칙

*   **한 번에 하나의 명확한 기능만 바꿉니다.**

*   **새 상태는 클래스나 객체에 묶습니다.** 낱개 전역 변수를 늘리기보다 관련 클래스 프로퍼티, 객체, 배열로 관리합니다.

*   **기존 전역 스크립트 구조를 존중합니다.**

*   **복잡한 계산에는 짧은 Why 주석을 답니다.** 회전, 그래프 탐색, 충돌, 거리 계산, 특수 조건처럼 다음 수정자가 실수하기 쉬운 곳에는 “왜 이 계산을 하는지”를 남깁니다.

*   **불필요한 객체는 제거합니다.** 화면 밖 장식, 판매된 블록, 수명이 끝난 텍스트 등은 `splice`, `filter` 등으로 배열에서 제거해 누수를 막습니다.

## 5. 파일 분리 기준

*   **생성자와 상태 초기화는 각 하위 폴더의 기본 파일에 둡니다.**

*   **입력, 렌더링, 계산, 특수 규칙은 별도 파일로 둡니다.** 기능을 찾을 때 파일명만 보고 진입점을 알 수 있어야 합니다.

*   **버튼은 화면 단위로 묶습니다.**

*   **파일이 다시 길어지면 책임 기준으로 나눕니다.** 단순히 줄 수로 자르지 말고 “입력”, “렌더링”, “계산”, “데이터 생성”, “상태 전환” 중 하나의 책임으로 분리합니다.

## 6. 번역 규칙

*   **게임 화면에 새 문구를 추가하면 `js/core/i18n.js`의 기존 번역 구조에 맞춰 한글과 영어를 함께 추가합니다.** 버튼, 대화상자, 상태 표시, 도움말, 튜토리얼 문구처럼 플레이어에게 보이는 문자열은 코드에 직접 박아두지 말고 `t()` 또는 `tList()`로 가져옵니다.

*   **같은 한국어 용어는 영어에서도 같은 표현으로 번역합니다.**

일단 이거를 AGENTS.md에 적고 코덱스한테 "AGENTS.md에 맞춰서 기본적인 게임 틀을 만들어줘"라고 명령하셈

그럼 알아서 몇 분간 작업할 거임

나중에 "아 이건 장기적으로 AI가 업데이트해야겠다"싶은 내용이 있으면 능동적으로 AGENTS.md를 수정해도 좋음

아니면 "니가 능동적으로 수정하도록 AGENTS.md에 내용을 추가해줘"라고 코덱스한테 요청해도 됨

3. 코드 요약 문서를 만들어

일단 위에서 명령 잘 내렸으면 알아서 CODE_SUMMARY.md를 만들었을 텐데, 아니면 CODE_SUMMARY.md를 만들어달라고 명령 내리셈

그러면 더 할 거 없음

할 말 없어서 잡설이나 풀자면, CODE_SUMMARY.md같은 문서 없으면 AI가 문서 전체 읽으면서 토큰 태워먹다보니 돈 아끼려면 CODE_SUMMARY.md같은 문서가 꼭 필요함

CODE_SUMMARY.md 말고도 코덱스의 게임 스튜디오 플러그인을 깐다던가, 아니면 관련 지침 문서를 인터넷에서 찾아서 .md으로 추가한다던가하는 것도 좋음

근데 지침 문서가 너무 많으면 간단한 명령에도 토큰 너무 잡아먹으니 "기본 지침은 컴팩트하게 적고, 복잡한 지침은 '필요시 읽을 것'이라고 표시하기"라는 규칙을 지키는 게 좋음

그리고 AI의 사고방식을 이해하면 좋은 게, AI는 진짜 "시킨 것만 함"

"알아서 잘 하기"라는 게 없으니 꼭 읽거나 참고해야 하는 문서가 있으면 AGENTS.md에 적거나 명령할 때마다 말해줘야함

물론 가끔 "와 이거를 눈치채서 해주네?"싶을 때도 있지만 항상 그런 건 아니니 그냥 조심하는 게 맞음

4. 명령을 대충 내리지 마

기본 세팅이 끝났으면 이번에는 "어떻게 명령을 내리냐"를 말해줄 거임

 

앞서 말했듯 AI는 기본적으로 "시킨 것만 하기"때문에 쓰레기같은 명령만 하면 쓰레기같은 코드가 나옴

게다가 그 쓰레기를 어떻게든 소화하겠다고 토큰을 엄청 잡아먹어서 비효율적이게 됨

그러니 기본적인 동작 구조는 미리 생각을 하고 명령을 내리는 게 나음

예를 들어 "복잡한 공격 패턴을 가진 보스를 만들어줘"라고 명령하지 말라는 거임

최소한 이렇게 명령하셈

```

다음과 같은 공격 패턴(1>2>3 반복)을 가진 보스를 추가해줘. 보스 이미지는 일단 피격 판정만 갖는 단순한 사각형 블럭으로 표현해.

1. 오른팔을 들고 2초 후에 내려찍는 공격

2. 무릎을 굽혔다가 1초 후에 플레이어 근처로 0.5초 동안 점프하고, 착지할 때 100픽셀 범위의 충격파를 내보내는 공격

3. 주머니에서 사과를 꺼내고 2초 동안 먹고, 그동안 공격 받지 않으면 생명력을 100 회복하는 패턴

기본 정보

공격력: 10

생명력: 1000

```

이런 식으로 적어도 "어떻게 구현될 것인지"에 대한 확실한 기획이 되어 있어야 함

그니까 정말로 "AI를 개발자로 쓴다"라고 생각해야 함

AI에게 기획자도 시키면 재미있는 게임이 안 나옴

정말 딱 "한 2년 정도 경력 있는 인간 개발자" 정도라고 생각하셈

"얘가 이 명령을 이해할까?"라고 고민하면서 충분히 "해석 가능한 명령"만 내리셈

또 중요한 건 "AI가 어떻게 오해할지"를 예측하는 거임

내가 위에서 "보스 이미지는 일단 피격 판정만 갖는 단순한 사각형 블럭으로 표현해."라고 말했지?

이유가 "이 AI가 혼자서 오해해서 막 AI 이미지 만들다가 토큰 태워먹겠구나!"라고 생각해서임

"AI가 오해해서 폭주할 경로"를 미리 차단해두는 것도 효율적인 AI 운용에 필요함

단 너무 과하게 통제하면 AI 해결 능력이 떨어지거나, 통제하다가 토큰 잡아먹으니 정말 "딱 오해하기 쉬운 부분"만 통제하는 게 중요함

참고

1. 저 AGENTS.md 복붙하면 서식이 약간 깨질 수 있는데, 이것도 그냥 코덱스한테 "AGENTS.md 서식 깨진 거 정상적으로 수정해줘"라고 명령하셈

2. 코덱스가 뭐가 권한 문제로 실패했다 아니면 다운로드가 안 된다 하면, 코덱스를 관리자 권한으로 실행해서 진행하면 되기도 함. 근데 이건 위험 요소도 좀 크니까 조심히 해

3. 코덱스에 플러그인이라고 있는데, 이거 깔면 AI가 알아서 도구 찾아서 진행하니까 편함. 뭐 깔지 모르겠으면 AI한테 물어봐

4. html 말고 고도나 유니티 기반으로 바이브 코딩하고 싶다? 그럼 난 몰?루니까 AI한테 물어봐

[고수만보면짖는뉴비(crime9255)]

고수

[사가다자(choice2234)]

[ㄴㄴ(giga010)]

자세한 지침은 진짜 필요한듯 일단 내가 구상이랑 설계는 다 짜고 구현만 봇 시켜야함 아니면 진짜 컴하하식 농담같은거 나옴

[사가다자(choice2234)]

[Indie 1(211.210)]

고수네

[사가다자(choice2234)]

[익명(head9220)]

관리자 권한(전체허용)말고 코덱스 '자동검토' 이거 쓰면 됨

[사가다자(choice2234)]

AI 작업 관련해서는 그러면 되긴 하는데, 가끔 설정 수정이나 플러그인 깔 때 가끔 관리자 권한 필요할 때도 있음. 설정 건드는 건 자동검토 설정 영향이 안 가니까

[Indie 2(1.233)]

이거보고 개발 시작함 ㄳㄳ