프로젝트 폴더와 작업 공간 준비하기

1. 2편에서 이어서 보기

2편에서는 터미널을 켜고 pwd, ls, cd, mkdir 같은 기본 명령어를 익혔다. 이제 바로 문서를 쓰기 전에, 내 컴퓨터 안에 이 앱을 위한 작업 공간을 먼저 만들어야 한다.

작업 공간은 어렵게 말하면 workspace이고, 쉽게 말하면 “이 앱과 관련된 파일을 모아 두는 자리”다. 이 안에 설계 문서, AI 지시 문서, 나중에 만들 코드 파일이 함께 들어간다.

이번 글의 목표는 간단하다.

• 내 컴퓨터에 프로젝트 폴더를 만든다.
• 그 안에 docs/ 폴더와 agent.md 자리를 만든다.
• 앞으로 만들 설계 문서가 들어갈 위치를 먼저 정한다.
• AI에게 작업을 맡기기 전에 “어디를 기준으로 읽어야 하는지”를 정한다.

아직 작업 계획 문서도 완성하지 않고, agent.md 내용도 길게 쓰지 않는다. 먼저 앱의 책상을 마련하고, 그 위에 빈 문서 파일을 하나씩 올려놓을 준비를 하는 단계라고 보면 된다.

2. 이번 글에서 새로 나오는 용어

1. 프로젝트 폴더: 한 앱에 필요한 파일을 모아 두는 기준 폴더
2. 폴더 구조: 폴더와 파일이 어떤 위치에 놓이는지 보여 주는 모양
3. 작업 공간: 내가 실제로 작업할 프로젝트 폴더 전체
4. 루트 폴더: 프로젝트 폴더의 가장 바깥쪽 위치

여기서 루트 폴더는 나무의 뿌리처럼 생각하면 된다. 예를 들어 myproject01이라는 프로젝트 폴더를 만들었다면, 그 폴더 안에 있는 docs/, agent.md, 코드 파일들이 모두 그 뿌리 아래에 놓인다.

3. 프로젝트 폴더는 어디에 만들까

이 시리즈에서는 사용하는 컴퓨터에 따라 아래 위치에 만든다. 위치를 매번 바꾸지 말고, 처음 정한 위치를 계속 쓴다.

macOS에서는 내 문서(Documents) 안에 프로젝트 폴더를 만드는 방식으로 시작한다.

내 문서/
└─ project/
   └─ myproject01/

macOS에서는 아래 위치에 만든다.

/Users/내이름/Documents/project/myproject01/

Windows 개인 컴퓨터에서는 드라이브 바로 아래에 project 폴더를 만드는 방식으로 시작한다.

C:\project\myproject01\

따라서 이 시리즈를 따라올 때는 아래 표대로 만든다.

폴더 이름은 myproject01으로 만든다. 한글 이름이나 띄어쓰기가 들어간 이름을 쓰지 않는다. 나중에 터미널이나 개발 도구에서 경로를 다룰 때 공백이나 한글 때문에 생기는 문제를 줄이기 위해서다.

4. 처음 만들 폴더 구조

이 시리즈에서는 아래 구조로 시작한다. 처음 프로젝트 폴더는 이 모양 그대로 만들면 된다.

myproject01/
├─ agent.md
└─ docs/
   ├─ 01-plan.md
   ├─ 02-structure.md
   └─ 03-data.md

각 파일의 역할은 다음과 같다. 지금은 내용을 모두 채우는 단계가 아니라, 앞으로 채울 빈 자리를 먼저 만들어 두는 단계다.

중요한 점은 docs/ 폴더가 상세 설계 보관함이고, agent.md는 그 설계 문서들을 가리키는 안내문이라는 것이다. 3편에서는 위치만 준비하고, 실제 내용은 4편부터 차례대로 채운다.

5. 작업 공간을 그림으로 보면

파일 배치를 그림으로 보면 이렇게 볼 수 있다.

이 그림에서 핵심은 myproject01이 기준 폴더라는 점이다. AI에게 작업을 부탁할 때도, 터미널에서 명령어를 실행할 때도, 편집기에서 폴더를 열 때도 이 폴더를 기준으로 생각한다.

6. 실제로 만들 때의 순서

파일 탐색기나 Finder로 만들 때는 아래 순서대로 만든다.

1. Documents 또는 C:\ 아래에 project 폴더를 만든다.
2. 그 안에 myproject01 폴더를 만든다.
3. myproject01 안에 docs 폴더를 만든다.
4. myproject01 안에 비어 있는 agent.md 파일을 만든다.
5. docs 안에 비어 있는 01-plan.md, 02-structure.md, 03-data.md를 만든다.
6. 다음 글부터 이 파일들을 하나씩 채운다.
7. 나중에 스택을 고른 뒤 docs/04-stack.md를 추가한다.

명령어로 만든다면 Windows에서는 아래처럼 입력한다.

macOS에서는 아래처럼 입력한다.

잘 만들어졌는지 확인하려면 아래 명령어를 입력한다.

agent.md와 docs/가 보이고, docs/ 안에 세 개의 파일이 있으면 성공이다.

명령어가 어렵다면 위 명령어를 외우지 않아도 된다. 대신 파일 탐색기나 Finder로 같은 모양을 만들면 된다. 중요한 것은 최종 모양이 아래 구조와 같아야 한다는 점이다.

Python은 이미 설치되어 있다고 가정한다. 아직 설치하지 않았다면 python.org에서 다운로드하거나, AI에게 "Python 설치 방법을 알려 주세요"라고 물어본다.

7. .md 파일을 만들 때 조심할 점

.md 파일은 Markdown 문서 파일이다. 어렵게 생각할 필요는 없다. 처음에는 메모장, TextEdit, VS Code 같은 편집기로 열 수 있는 글 문서라고 생각하면 된다.

파일 탐색기나 Finder로 만들 때는 다음을 확인하자.

1. 파일 이름이 정확히 agent.md인지 확인한다.
2. docs 폴더 안에 01-plan.md, 02-structure.md, 03-data.md가 있는지 확인한다.
3. Windows에서 파일 확장자가 숨겨져 있으면 agent.md.txt처럼 만들어질 수 있으니 조심한다.
4. 파일 내용은 비어 있어도 된다. 지금은 "내용 완성"이 아니라 "자리를 만들기"가 목표다.

Windows에서 확인이 어렵다면 파일 탐색기 상단의 보기 옵션에서 파일 확장명을 보이게 설정하면 좋다. 그래야 agent.md인지 agent.md.txt인지 구분할 수 있다.

VS Code 같은 편집기를 쓴다면 myproject01 폴더 전체를 열면 된다. 이때 가장 바깥에 보이는 폴더가 myproject01이면 제대로 연 것이다.

8. AI에게 작업 공간을 설명하는 프롬프트

이 프롬프트의 목적은 AI에게 코드를 만들어 달라고 하는 것이 아니다. 내가 만든 프로젝트 폴더가 이 시리즈에서 정한 출발 구조와 맞는지 확인받는 것이다.

AI나 인터넷 튜토리얼은 처음부터 복잡한 폴더 구조를 만들도록 안내하기도 한다. 이 시리즈에서는 그렇게 하지 않는다. 지금은 myproject01, agent.md, docs/ 세 가지만 기준으로 시작한다. 더 많은 폴더가 필요해지는 순간이 오면, 그때 하나씩 추가한다.

그래서 이 질문은 쉽게 말해 다음을 확인하는 절차다.

• myproject01이 프로젝트의 기준 폴더로 잡혀 있는가?
• agent.md가 myproject01 바로 아래에 있는가?
• docs/ 안에 01-plan.md, 02-structure.md, 03-data.md가 있는가?
• 아직 코드 폴더를 만들지 않고 문서 자리부터 준비했는가?

작업 공간을 만들었다면 AI에게 이렇게 말할 수 있다.

저는 아직 코드를 만들려는 것이 아니라,
작은 앱을 만들기 전에 작업 공간을 먼저 정리하고 있습니다.

프로젝트 폴더 이름은 myproject01입니다.

현재 폴더 구조는 아래처럼 준비하려고 합니다.

myproject01/
├─ agent.md
└─ docs/
   ├─ 01-plan.md
   ├─ 02-structure.md
   └─ 03-data.md

저는 이 시리즈를 따라가며 이 구조로 시작하려고 합니다.

아래 네 가지만 확인해 주세요.

1. agent.md가 myproject01 바로 아래에 있는지
2. docs 폴더 안에 01-plan.md, 02-structure.md, 03-data.md가 있는지
3. 아직 코드 폴더를 만들지 않았는지
4. 다음 단계에서 docs/01-plan.md부터 채우면 되는 구조인지

아직 코드는 만들지 말고,
위 네 가지가 맞는지만 짧게 확인해 주세요.

예상 결과는 코드가 아니라 폴더와 문서 배치에 대한 짧은 확인이다. AI가 “네, 이 구조로 시작하면 됩니다”, “다음 단계에서는 docs/01-plan.md부터 채우면 됩니다”처럼 답한다면 정상이다.

즉, 이 프롬프트의 의미는 “앱을 만들어 주세요”가 아니라 “이 시리즈에서 정한 시작 구조대로 준비됐는지 확인해 주세요”에 가깝다. 이 확인을 한 번 거치면 다음 글에서 docs/01-plan.md를 채울 때, 문서를 어디에 둘지 다시 고민하지 않아도 된다.

나중에 docs/01-plan.md, docs/02-structure.md, docs/03-data.md, agent.md까지 실제 내용이 채워진 뒤에는 다시 다른 질문을 하게 된다. 그때는 “이 문서들을 읽고 첫 코드를 만들어 주세요”라고 요청한다. 지금 질문은 그보다 앞 단계인 빈 작업 공간 점검이다.

9. 지금은 만들지 않는 것

AI에게 "앱 폴더 만들어 줘"라고 물어보면, 이런저런 영문 폴더를 잔뜩 제안할 수 있다. 그런 제안을 받더라도 지금은 추가하지 않는다.

지금 만드는 것은 myproject01, agent.md, docs/, 그리고 docs/ 안의 세 문서 파일뿐이다. 그 외의 폴더는 나중에 실제로 코드를 만들 때, 정말 필요해진 순간에 하나씩 추가한다.

처음 작업 공간은 아래처럼 고정해서 시작한다.

myproject01/
├─ agent.md
└─ docs/
   ├─ 01-plan.md
   ├─ 02-structure.md
   └─ 03-data.md

10. 다른 AI 코딩 도구를 쓴다면

이 시리즈는 opencode를 기준으로 설명한다. 다른 AI 코딩 도구를 쓴다면 명령어만 바꾸면 된다.

도구가 달라도 다음 흐름은 같다.

1. 프로젝트 폴더에서 도구를 실행한다.
2. agent.md와 docs/ 안의 문서를 읽게 한다.
3. 자연어로 요청한다.
4. 결과를 확인하고 다시 요청한다.

11. 다음 글에서 할 일

오늘 여기까지 했으면 성공

이번 글을 끝내고 나면 내 컴퓨터에는 myproject01 폴더가 있고, 그 안에 docs/ 폴더와 비어 있는 문서 파일들이 있어야 한다. 내용이 비어 있어도 괜찮다. 오늘의 목표는 문서 내용을 완성하는 것이 아니라, 문서를 넣을 자리를 만드는 것이다.

이번 글에서는 앱을 만들기 전에 프로젝트 폴더와 문서 위치를 먼저 정했다.

다음 글에서는 이 작업 공간 안의 docs/01-plan.md를 채워 볼 것이다. Python으로 만들 작은 앱의 목적과 기능을 정리한다. 앱 이름, 목적, 사용자, 기능 목록, 입력, 출력, 로직, 자료 형태를 하나씩 적으면서 작업 계획 문서를 만든다.

즉, 순서는 다음과 같다.

1. 프로젝트 폴더를 만든다.
2. docs/ 폴더를 만든다.
3. docs/01-plan.md를 연다.
4. 만들 앱의 목적과 기능을 적는다.
5. 그다음 작업 계획 문서와 AI 지시 원칙으로 넘어간다.

이 순서를 지키면 “문서는 있는데 어디에 넣어야 하지?”라는 혼란 없이, 실제 앱 폴더 안에서 설계를 쌓아 갈 수 있다.