낯선 프로젝트 파악하기

처음 보는 프로젝트의 폴더를 IDE에서 열었습니다. 중첩된 폴더가 수십 개 있고 이름도 낯설며, 직접 작성한 파일은 하나도 없습니다. 이제 변경 작업을 해야 합니다. 처음에는 페이지를 조금 수정하고, 나중에는 새 게임도 추가할 예정입니다. 시작하기 전에 필요한 파일이 어디에 있는지, 프로젝트에서 어떤 규칙을 따르는지 파악해야 합니다.

필요한 곳을 찾으려고 폴더를 하나씩 열어 보고 싶을 수 있습니다. 하지만 먼저 프로젝트의 전체 구조와 규칙을 파악하는 편이 낫습니다. 작은 수정에도 도움이 되고, 나중에 새 게임을 추가할 때도 파일 이름과 위치를 정하고 Claude Code와 함께 결과를 확인하는 데 쓸 수 있습니다.

프로젝트의 시작점을 찾으세요

IDE의 파일 트리에서 프로젝트 루트에 있는 README.md를 찾으세요. 이 파일은 프로그램이 아니라 사람을 위해 작성한 일반 텍스트입니다. 보통 어떤 프로젝트인지, 어떻게 실행하는지 간단히 설명합니다. 물론 프로젝트 이름만 적혀 있고 나머지는 알아서 파악하라는 경우도 있습니다. 사람은 게으르고 README는 저절로 작성되지 않으니까요 :)

README에서 보통 세 가지를 알 수 있습니다. 프로젝트의 목적, 실행 방법, 더 자세한 안내로 가는 링크입니다. 예를 들어 아키텍처나 코드 스타일을 설명하는 별도 파일이 있을 수 있습니다. 페이지를 조금 수정하는 정도라면 전체적인 그림을 파악하기에 충분합니다.

README가 없거나 코드와 맞지 않을 수도 있습니다. 우선 출발점으로 삼고, 명령어와 폴더에 관한 내용은 실제 프로젝트 파일과 대조하세요. 문서에 적힌 구조와 파일 트리에 보이는 구조가 다르다면 확인할 질문으로 남겨 두세요.

폴더 트리가 알려 주는 것

게임 목록, 점수 집계, 결과 표가 있는 작은 브라우저 게임 포털을 예로 들어 보겠습니다. 폴더 트리의 일부는 다음과 같습니다.

project/
├── README.md
├── package.json
├── vite.config.js
├── pages/
│   └── leaderboard.html
├── src/
│   ├── leaderboard.js
│   └── reward-flow.js
├── assets/
├── tests/
└── dist/

코드를 한 줄도 읽지 않았는데도 폴더 트리에서 몇 가지를 짐작할 수 있습니다.

폴더 이름은 단서일 뿐, 확인된 사실은 아닙니다. 이름만 보면 src/leaderboard.js가 필요한 파일 같지만, 실제로 읽어 보고 어디서 불러오는지 찾아야 합니다. 위 표의 폴더 역할도 아직 확인해야 할 예상입니다. 특히 tests/가 있다고 해서 검사를 어떻게 실행하는지는 알 수 없습니다.

소스 코드와 그 코드로 생성되거나 외부에서 설치된 결과물은 구분해야 합니다. 보통 dist/는 빌드 도구가 src/의 내용으로 생성합니다. 외부 의존성을 담은 폴더(예를 들어 node_modules/, 위 예시에는 없음)는 팀원이 직접 작성한 코드가 아닙니다. 이런 폴더부터 읽는 것은 대개 의미가 없습니다. 거기서 수정한 내용은 다음 빌드 때 사라지거나, 직접 편집하지 않는 다른 사람의 코드를 건드리게 되니까요. 패키지 관리자와 의존성 설치, lockfile 형식은 별도 주제라 여기서는 다루지 않습니다.

그리고 예시의 폴더 구성이 표준은 아닙니다. 다른 프로젝트에서는 페이지가 public/에, 소스 파일이 app/에 있을 수 있습니다. 찾는 방법은 같고 폴더 이름만 달라집니다.

프로젝트 작업 규칙

폴더가 어떤 역할을 하는지 파악했다고 해 보겠습니다. 파일을 추가하기 전에 프로젝트에서 정한 작업 방식을 알아보세요. 어떤 프로젝트는 모든 페이지를 한 폴더에 두고, 다른 프로젝트는 게임마다 스크립트와 이미지와 함께 보관합니다. 둘 다 괜찮은 방식입니다. 문제는 새 게임을 제3의 방식으로 구성하면서 그 이유를 어디에도 설명하지 않는 경우입니다.

README에 있는 링크를 따라가며 프로젝트의 약속을 찾아보세요. CONTRIBUTING.md가 있다면 보통 변경 사항을 반영하는 방법을 설명합니다. 문서에는 파일 배치 규칙이, CLAUDE.md에는 에이전트 지침이 있을 수 있습니다. 개별 폴더에 그 안의 내용을 설명하는 README가 따로 있을 수도 있습니다. 모든 프로젝트에 이 파일이 다 있다고 기대할 필요는 없습니다. 필요한 규칙 몇 가지가 루트 README 하나에 담겨 있기도 합니다.

첫 수정 작업에는 어떤 소스 파일을 변경해도 되는지, 파일 이름과 위치를 어떻게 정하는지, 프로젝트를 실행하고 결과를 확인하는 방법만 알아도 충분합니다. 빌드 결과물 수정을 금지하는 안내가 있다면 원본 파일을 찾으세요. 페이지 추가 시 설명도 갱신하라고 되어 있다면 처음부터 작업에 포함하세요.

문서로 된 규칙이 없다면 비슷한 예시를 두세 개 살펴보세요. 새 게임을 추가할 때는 임의의 문서 폴더보다 이웃한 게임을 참고하는 편이 낫습니다. 비슷한 파일 배치 방식을 본보기로 삼을 수는 있지만, 오래된 파일 하나만으로 프로젝트 전체가 그렇게 구성되었다고 단정할 수는 없습니다.

더 난감한 경우도 있습니다. README에서는 페이지를 pages/에 두라고 하는데 최근 게임은 다른 곳에 있습니다. 이럴 때는 프로젝트 담당자에게 구체적으로 물어보세요. "안내에는 pages/라고 되어 있는데 새 게임 두 개는 games/에 있습니다. 다음 게임은 어디에 추가할까요?" 마음에 드는 방식을 말없이 고르거나 일관성을 위해 전체 구조를 옮기지는 마세요.

파일과 폴더 이름 규칙

네이밍은 이름을 정하는 약속입니다. 좋은 이름은 파일 트리에서 필요한 파일을 찾고 열어 보기 전에도 용도를 파악하게 해 줍니다. 이 포털에서 leaderboard.html은 결과 표라는 것을 알려 주지만, page2.html은 누군가 정한 순번만 알려 줍니다.

이름에는 의미와 형식이 있습니다. 의미는 "여기에 무엇이 있나요?"에 답하고, 형식은 대소문자와 단어 사이의 구분자를 정합니다. 예를 들어 일일 보상 페이지 이름은 다음과 같이 지을 수 있습니다.

이것들은 표기 방식이지 순위가 아닙니다. 프로젝트 페이지 이름에 하이픈을 쓴다면 새 페이지도 같은 스타일로 지으세요. 파일 종류에 따라 규칙이 다를 수도 있습니다. 익숙한 README.md 이름을 HTML 페이지와 맞춘다고 소문자로 바꿀 필요는 없습니다. 도구가 기대하는 이름도 그대로 유지하세요.

포털의 일반 파일에는 영어 단어와 kebab-case를 쓰기로 했다고 해 보겠습니다. 그러면 snake-preview.png가 img3.png보다 이해하기 쉽습니다. 스네이크 게임의 미리 보기라는 뜻이니까요. game-icons/ 폴더는 stuff/보다 안에 무엇이 있는지 잘 알려 줍니다. leaderboard-final-new.html은 다음 수정만 해도 금세 낡은 이름이 됩니다. 실제 페이지에는 용도를 나타내는 오래 쓸 수 있는 이름을 붙이세요.

같은 대상을 가리키는 용어는 하나로 통일하세요. 프로젝트의 게임 폴더가 games인데 같은 종류의 파일을 plays에 넣으면 둘 사이에 차이가 있는지 독자가 고민하게 됩니다. 프로젝트 규칙에 없는 한 ldrbrd/ 같은 수수께끼 같은 축약어도 피하세요.

철자를 정확히 쓰는 것도 중요합니다. 파일 이름과 경로는 대소문자까지 일치해야 합니다. Snake.png와 snake.png를 서로 바꿔 써도 된다고 생각하면 안 됩니다. 한 컴퓨터에서는 드러나지 않은 오류가 다른 환경에서 나타날 수 있습니다. 이 예시에서는 소문자를 쓴다는 약속이 이런 불일치를 줄여 줍니다.

폴더 중첩 규칙

이름을 정했다면 다음은 파일을 어디에 둘지입니다. 하위 폴더는 게임 페이지, 한 게임의 이미지, 공용 아이콘처럼 분명한 그룹으로 묶을 때 유용합니다. 단계가 하나 늘어날 때마다 콘텐츠를 찾기 쉬워야 합니다.

다른 경우를 생각해 보죠. 포털이 커지는데 모든 파일을 루트에 바로 넣는다고 해 봅시다.

project/
├── README.md
├── package.json
├── snake.html
├── tetris.html
├── leaderboard.html
├── snake.js
├── tetris.js
├── snake-preview.png
└── tetris-preview.png

예시가 작을 때는 여전히 파악할 수 있습니다. 게임이 스무 개쯤 되면 페이지, 스크립트, 이미지가 서로 뒤섞이겠죠. 이 포털은 이미 pages/, src/, assets/로 나뉘어 있으니 게임을 추가할 때도 이 방식을 이어 가는 편이 자연스럽습니다. 추가 후 구조의 일부는 다음과 같을 수 있습니다.

project/
├── pages/
│   ├── leaderboard.html
│   └── games/
│       ├── snake.html
│       └── tetris.html
├── src/
│   ├── leaderboard.js
│   └── games/
│       ├── snake.js
│       └── tetris.js
└── assets/
    └── games/
        ├── snake/
        │   └── preview.png
        └── tetris/
            └── preview.png

게임 페이지는 한 그룹으로, 각 페이지의 스크립트는 다른 그룹으로 모았습니다. 게임 이름이 파일들을 연결해 줍니다. 이미지에는 게임별 폴더가 있으므로 preview.png처럼 짧은 이름만으로도 충분합니다. 전체 경로가 어떤 게임의 미리 보기인지 설명해 주니까요. 같은 게임의 다른 이미지를 둘 때도 별도 폴더가 유용합니다.

반대쪽 극단은 pages/portal/content/browser/games/arcade/snake/screens/main/index.html 같은 경로입니다. 페이지 하나를 열기 위해 여러 단계의 폴더를 거쳐야 하고, 이름 중에는 정보를 거의 더해 주지 않는 것도 있습니다. 프로젝트에 별도의 포털, 화면, 카테고리가 없다면 이런 구조는 쓸데없는 일만 늘립니다.

"폴더를 세 단계보다 깊게 만들지 말라" 같은 보편적인 기준은 없습니다. 각 단계가 무엇을 묶고, 이 그룹을 주변 그룹과 구별하는 데 도움이 되는지 살펴보세요. 도구나 프로젝트 규칙 때문에 파일 하나만 든 폴더가 필요한 경우도 있습니다. 하지만 "나중에 뭔가 생길지도 모르니까"라는 이유만으로 폴더를 만들기에는 대개 이릅니다.

위 트리는 예시가 확장되는 모습을 보여 줍니다. 여러분의 프로젝트에서 각 게임이 이미 자기 폴더에 통째로 들어 있다면 그 방식을 이어 가세요. 새 게임을 추가한다고 해서 기존 구조를 바꿀 필요는 없습니다.

공용 파일과 로컬 파일 보관하기

스네이크 게임에 사과 이미지가 생겼고, 포털 전체에서 쓸 공용 로고도 있습니다. 둘 다 이미지 파일이지만 쓰임새는 다릅니다. 사과 이미지는 한 게임에만 필요하고, 로고는 게임 목록과 결과 표, 게임 페이지에서 사용합니다.

한 게임의 파일은 그 게임에서만 사용합니다. 이 절에서는 이런 파일을 로컬 파일이라고 부릅니다. 컴퓨터나 서버에 저장된 위치가 아니라 사용 범위를 말하는 겁니다. 이 트리에서 사과는 assets/games/snake/apple.png에 둡니다. 공용 파일은 여러 부분에서 필요합니다. 프로젝트에서 정한 폴더라면 로고를 assets/shared/portal-logo.svg에 둘 수 있습니다. shared는 "공용"이라는 뜻이지만, 폴더 이름 자체가 파일에 특별한 속성을 부여하지는 않습니다.

스타일과 스크립트도 같은 기준으로 나눌 수 있습니다. 스네이크 게임판의 스타일은 해당 게임에 속하고, 공용 헤더의 스타일은 포털 전체에 쓰입니다. 파일을 둘 위치를 정할 때 지금 누가 사용하는지 확인하세요. 나중에 재사용할지도 모른다는 이유로 모든 파일을 미리 공용 폴더로 옮길 필요는 없습니다.

반대로 로고 하나를 각 게임 폴더에 복사해 두면 번거롭습니다. 교체할 때 모든 복사본을 찾아야 하니까요. 정말 공용 리소스라면 하나의 파일을 참조하는 편이 낫습니다. 서로 다른 게임의 비슷한 이미지 두 개는 별개로 둘 수도 있습니다. 겉모습이 비슷하다고 늘 함께 변경되는 것은 아니니까요.

그림에서 공용 로고에는 화살표 세 개가, 사과 이미지에는 하나만 연결됩니다. 따라서 로고를 바꾼 뒤에는 세 페이지를 모두 확인하고, 사과를 바꾼 뒤에는 스네이크 페이지를 확인하세요. 수정하기 전에 Claude Code에 해당 리소스를 참조하는 파일을 찾아 달라고 하면 좋습니다. 실제 참조 관계가 폴더 이름만 보고 예상한 것보다 많을 수 있습니다.

파일을 옮기거나 이름을 바꿀 때 확인할 것

파일 이름은 순식간에 바꿀 수 있지만, 이전 이름이 링크와 설정에 이미 적혀 있을 수 있습니다. 파일을 옮기면 다른 파일과의 상대적인 위치도 달라집니다. 그러므로 파일 트리를 정리하는 일도 페이지 내용을 바꾸는 것처럼 프로젝트를 수정하는 작업입니다.

별도의 이동 예를 보겠습니다. pages/snake.html 페이지를 pages/games/snake.html로 옮겼습니다. 스크립트 src/games/snake.js는 그대로입니다. 이 예시의 상대 경로는 HTML 페이지의 주소를 기준으로 계산합니다. 옮긴 뒤에는 연결 경로를 바꿔야 합니다.

<!-- pages/snake.html에서 이동 전 -->
<script src="../src/games/snake.js" type="module"></script>

<!-- pages/games/snake.html에서 이동 후 -->
<script src="../../src/games/snake.js" type="module"></script>

../ 하나마다 상위 폴더로 한 단계 올라갑니다. 이제 games/에서 pages/로 나간 뒤 루트로 올라가야 src/에 들어갈 수 있습니다. 스크립트 자체는 바뀌지 않았지만 이전 경로는 더 이상 맞지 않습니다.

반대 방향의 링크도 있습니다. 게임 목록의 게임 카드가 여전히 이전 페이지 주소로 연결될 수 있습니다. 파일을 옮기기 전에 프로젝트 전체에서 이전 경로를 찾아보세요. 이동한 뒤에는 필요한 링크와 연결, 빌드 설정, 문서의 예시를 업데이트하세요. 스크립트 이름을 바꿨다면 다른 스크립트가 이 스크립트를 불러오는 import 구문도 확인해야 합니다.

IDE가 일부 링크를 자동으로 업데이트할 수 있지만, 결과는 직접 살펴보세요. 경로가 항상 한 줄로 적혀 있는 것은 아닙니다. 폴더 이름과 파일 이름을 조합해 주소를 만드는 경우도 있습니다. 따라서 이전 이름을 검색해 의존성을 찾고, 필요한 시나리오를 실행해 빠뜨린 곳이 있는지 확인하세요.

수정 결과 확인하기

먼저 프로젝트 문서에서 실행, 빌드, 테스트 명령어를 찾으세요. package.json이 있는 프로젝트라면 안내 내용을 scripts 항목과 대조하세요. 명령어 이름은 프로젝트마다 다릅니다. tests/ 폴더가 있다고 해서 어떤 명령어를 실행해야 하는지는 알 수 없습니다. 안내가 없다면 익숙한 명령어를 짐작해 쓰지 말고 확인 방법을 물어보세요.

그다음에는 어떤 변경을 했는지에 따라 확인할 내용이 달라집니다. 스네이크 페이지를 옮긴 뒤에는 게임 목록의 카드를 통해 열어 보세요. 페이지 이동과 게임 로딩을 함께 확인할 수 있습니다. 이미지가 표시되고 게임이 실행되는지 확인하세요. 공용 로고를 바꿨다면 결과 표와 다른 게임 페이지 하나도 살펴보세요.

빌드가 성공하면 도움이 되지만, 이 확인을 대신하지는 않습니다. 빌드된 프로젝트에도 이전 주소로 가는 링크가 남아 있을 수 있습니다. 무엇을 확인했고 아직 확인하지 못한 것이 무엇인지 기록하세요. 예를 들면 "빌드가 완료됐고, 게임 목록에서 스네이크를 열어 실행했습니다. 좁은 화면에서 표시되는 모습은 확인하지 않았습니다"라고 적을 수 있습니다.

마지막으로 변경된 파일 목록을 살펴보세요. 게임 하나를 추가했다면 그 게임의 파일과 게임 목록 수정 정도가 예상됩니다. 다른 게임의 폴더 이름이 바뀌었거나 이미지가 한꺼번에 덮어쓰였다면 이유가 있어야 합니다. 나중에 뜻밖의 오류를 찾는 것보다 지금 목록을 확인하는 편이 빠릅니다.

Claude Code에 규칙 전달하기

"게임을 깔끔하게 추가해 줘"라는 요청에는 에이전트가 결정할 일이 너무 많습니다. 작업 내용을 명확히 말하고 먼저 프로젝트의 약속을 살펴보라고 하는 편이 낫습니다. 새 게임의 경로도 에이전트의 즉흥적인 취향이 아니라 프로젝트 구조를 따라야 합니다.

계속 적용할 검증된 규칙은 CLAUDE.md에 기록할 수 있습니다. 이 포털의 규칙 일부를 적으면 다음과 같습니다.

## 파일과 폴더
- 일반 파일과 폴더 이름에는 kebab-case 영어 단어를 사용합니다.
  README.md와 CLAUDE.md처럼 정해진 이름은 그대로 둡니다.
- 게임 페이지는 pages/games/에, 게임 스크립트는 src/games/에 둡니다.
- 게임별 리소스는 assets/games/<game-name>/에 둡니다.
- 포털의 공용 이미지는 assets/shared/에 둡니다.
- 파일을 옮기거나 이름을 바꾸면 해당 파일을 가리키는 링크와
  파일 내부의 상대 경로를 업데이트합니다.

## 확인
- 실행 및 테스트 명령어는 README.md에서 확인합니다.
- 새 게임을 게임 목록에서 열어 실행을 확인합니다.
- 공용 리소스를 변경한 뒤에는 이를 사용하는 페이지를 확인합니다.

이것은 합의된 규칙의 예시이지, 어디에나 적용되는 폴더 트리 템플릿은 아닙니다. 비슷한 내용을 여러분의 프로젝트에 기록하기 전에 실제 파일에서 경로와 명령어를 확인하세요. 에이전트가 폴더의 역할을 추측했을 뿐이라면 근거를 보여 달라고 하세요. 추측을 계속 적용할 지침으로 만들지는 마세요.

이제 게임 추가 작업을 다음과 같이 요청할 수 있습니다.

첨부한 설명을 참고해 포털에 memory-match 게임을 추가해야 합니다.
README.md, CLAUDE.md와 작업 대상 폴더의 지침을 읽으세요.
기존 게임 두 개의 파일이 어떻게 배치되어 있는지 살펴보세요.
새 페이지, 스크립트, 이미지의 이름과 경로를 제안하세요.
수정해야 할 게임 목록 파일과 결과 확인 방법을 알려 주세요.
지침과 프로젝트 구조가 맞지 않으면 질문하세요.
먼저 계획을 보여 주고 승인을 기다린 다음 수정하세요.

계획을 보면 구체적인 선택을 미리 검토할 수 있습니다. 게임을 어디에 둘지, 어떤 파일이 공용인지, 작업이 다른 페이지에 영향을 주는지 확인하세요. 수정이 끝난 뒤에는 변경된 파일과 실행한 검사를 나열해 달라고 하세요. 합의한 내용과 결과를 비교하기 쉬워집니다.