콘텐츠로 이동

저장소 모양

Webcraft 프로젝트는 어디를 열어도 같은 자리에 같은 종류의 코드가 있어요. 그래서 처음 보는 기능도 어디부터 읽을지 바로 알 수 있고, 에이전트도 새 코드를 어디에 둘지 헤매지 않아요. 이 장은 저장소 루트의 모양을 설명해요.

프론트엔드와 백엔드를 한 저장소의 두 폴더로 둬요. 왜 하나로 두는지는 그래도 저장소는 하나예요에 있어요. 아래는 cowork 저장소의 루트예요.

  • 디렉터리cowork/
    • 디렉터리web/ 프론트엔드(React)
      • 디렉터리src/
        • …
      • package.json
      • vite.config.ts
    • 디렉터리server/ 백엔드(Spring Boot)
      • 디렉터리src/
        • …
      • build.gradle
      • openapi.json 서버가 만든 API 계약
    • 디렉터리scripts/
      • wait-for-server.mjs 서버가 뜬 뒤에 화면을 띄우게 기다리기
    • AGENTS.md 에이전트가 읽는 프로젝트 안내
    • CLAUDE.md @AGENTS.md 한 줄
    • Dockerfile 서버와 화면을 이미지 하나로 빌드
    • dev.sh 개발할 때 서버와 화면을 띄우기
    • README.md

AGENTS.md는 에이전트가 이 프로젝트에서 일할 때 먼저 읽는 안내예요. Codex는 이 파일을 바로 읽고, Claude Code는 CLAUDE.md의 @AGENTS.md 한 줄을 거쳐 같은 파일을 읽어요. 그래서 안내의 원본은 AGENTS.md 하나예요.

cowork의 AGENTS.md에는 이런 것이 들어 있어요.

절 내용
구성 server/와 web/이 무엇으로 되어 있는지, 모듈과 키트를 어디에 두는지
개발 지침 이 프로젝트가 Webcraft 지침을 따른다는 것과, 작업할 때 함께 읽을 지침
프로젝트 규칙 Webcraft 지침과 다르게 정한 것과 그 이유
실행과 검증 sh dev.sh, 서버와 화면을 바꾼 뒤 돌릴 검사 명령

Webcraft 지침을 그대로 베껴 두지 않고, 이 프로젝트만의 예외만 적어요.

web/과 server/ 안쪽은 각자의 규칙으로 나눠요.

프론트엔드 코드 구조

web/src를 다섯 층으로 나누고, pages 폴더가 주소를 정해요. 코드 구조에서 볼 수 있어요.

백엔드 코드 구조

서버를 모듈로 나누고, 모듈 안을 application·domain·infrastructure로 나눠요. 코드 구조에서 볼 수 있어요.

규칙 원문

에이전트가 따르는 규칙 전체는 규칙 목록에서 볼 수 있어요.

실제 코드

이 구조로 만든 제품은 cowork에서 볼 수 있어요.