종합 실습

프로젝트를 만들기 전에, 무엇을 만들지부터 정리합니다. 그 정리가 스펙(spec) 문서 입니다.

• 스펙이 분명하면 개발이 빠르고 정확합니다.
• onboarder: 질문에 답하기만 하면 개발 스펙 문서를 자동으로 만들어 주는 사내 도구.
• 흐름: onboarder 로 스펙 생성 → 스펙을 프로젝트 docs 에 넣기 → 그 스펙대로 개발

브라우저에서 프로젝트 대시보드로 접속합니다. 로그인은 필요 없습니다.

https://onboarder-dev.popupstudio.ai/projects/dashboard/

프로젝트 목록이 보입니다.

1. 새 프로젝트 를 누릅니다.
2. 이름과 설명을 적습니다.
3. 예: 이름 법인세 보고서 자동화, 설명 세무조정계산서 분석 → 법인세 분석 보고서 생성
4. 생성 을 누르면 상세 페이지로 넘어갑니다.

만들 기능과 관련된 참고 자료를 올립니다. AI 가 이걸 읽고 질문을 준비합니다.

실습용 자료는 예제 프로젝트 법인세 보고서 자동화 8 의 내보내기 zip 안 data/ 폴더에 들어 있습니다. 아래 주소로 zip 을 받아 압축을 풀면 data/ 폴더가 나옵니다.

https://onboarder-dev.popupstudio.ai/api/projects/ho91hax3lguqnc15/export/

1. 상세 페이지에 data/ 안의 파일들을 드래그해서 올립니다.
2. 파일 분석 시작 을 누릅니다.
3. 분석이 끝날 때까지 기다립니다. (자료 양에 따라 1~5분)

AI 가 만든 질문에 답하면서 빈 곳을 채웁니다.

1. Q&A 인터뷰 를 누릅니다.

2. 질문에 답합니다. 위쪽 충분도 바가 100% 에 가까워지게 합니다.

3. 답변 팁

   • 구체적으로: "억원 단위, 소수점 둘째 자리" 처럼.
   • 예시 포함: 실제 값이나 예시를 함께.
   • 모르면: "미정" 이라고 답해도 됩니다.

1. 스펙 문서 생성 을 누릅니다.
2. 개요·입력·처리·출력·예외·규칙이 정리된 스펙 문서가 나옵니다.
3. 내용이 부족하면 재생성 을 누릅니다.

스펙 화면의 개발 프로젝트로 내보내기(.zip) 를 눌러 zip 을 내려받습니다.

1. 받은 zip 의 압축을 풉니다. (zip 파일을 그대로 쓰면 안 됩니다.)
2. 풀면 안에 docs/spec/ 폴더가 있습니다. 그 안의 spec 폴더를 씁니다.
3. 서버에 연결된 VS Code 를 엽니다(환경 준비에서 접속한 그 VS Code). 왼쪽 탐색기에서 프로젝트의 src/docs 폴더를 펼칩니다.
4. 압축 푼 spec 폴더를 그 src/docs 위로 끌어다 놓습니다(드래그). 서버로 올라갑니다.
5. 왼쪽 목록에 src/docs/spec/development_spec.md 가 보이면 성공입니다.

프로젝트 세션에서 그 스펙대로 만들어 달라고 요청합니다.

# 🖥️ 서버 터미널
gildong@ip-172-31-39-132:~$ cd ~/my_project/src
gildong@ip-172-31-39-132:~/my_project/src$ claude

docs/spec/development_spec.md 스펙대로 개발해줘

• "무엇을 만들지" 가 스펙에 또렷하니, 맨땅에서 설명할 때보다 훨씬 빠르고 정확하게 나옵니다.

• 핵심 정리: onboarder 로 스펙 문서를 만들어(생성 → 업로드·분석 → Q&A → 스펙) 프로젝트 docs 에 넣고, 그 스펙대로 개발했습니다. 스펙부터 잡으면 개발이 빠릅니다.
• 주의 사항: 스펙이 두루뭉술하면 결과도 두루뭉술합니다. Q&A 에서 구체적으로 답하는 것이 핵심입니다.
• 다음 시간: 이제 이 스펙을 바탕으로 프로젝트를 처음부터 만들어 봅니다.

지금까지 배운 것을 종합해 스스로 한 바퀴 도는, 본격 실무 전 마지막 연습입니다.

• 앞에서 onboarder 로 만든 법인세 보고서 자동화 스펙으로, 그 프로젝트를 처음부터 개발합니다.
• 흐름: 프로젝트 생성 → 스펙 넣기 → 첫 기능 → 커밋·푸시
• 각 단계의 자세한 방법은 앞 레슨에 있습니다. 여기선 순서대로 직접 해봅니다.

런처에서 Claude Code 를 켜고 생성을 요청합니다.

# 🖥️ 서버 터미널
gildong@ip-172-31-39-132:~$ cd ~/standarda-devtools
gildong@ip-172-31-39-132:~/standarda-devtools$ claude

create-project 로 'tax_report' 만들어줘

/exit

이어서 준비 스크립트를 실행합니다.

# 🖥️ 서버 터미널
gildong@ip-172-31-39-132:~$ cd ~/tax_report
gildong@ip-172-31-39-132:~/tax_report$ ./setup.sh

• 흔한 실수: create-project 는 반드시 런처(~/standarda-devtools)에서 요청합니다. 다른 폴더에서 하면 도구를 못 찾습니다.

• 내보내기 zip 압축을 풀어 spec 폴더를 tax_report/src/docs/ 에 복사 → src/docs/spec/development_spec.md
• 흔한 실수: zip 파일을 그대로 docs 에 두면 안 됩니다. 반드시 압축을 풀고 spec 폴더만 넣습니다.

# 🖥️ 서버 터미널
gildong@ip-172-31-39-132:~$ cd ~/tax_report/src
gildong@ip-172-31-39-132:~/tax_report/src$ claude

개발 서버 띄워줘

docs/spec/development_spec.md 스펙의 첫 기능부터 만들어줘

• 중간의 계획·스펙 확인에 답합니다.
• 흔한 실수: 요청이 막연하면 엉뚱하게 나옵니다. 무엇을 입력하면 화면에 무엇이 보이는지 한 문장으로 적으면 정확해집니다.

지금까지 변경한 내용을 깃허브에 올려줘

• 흔한 실수: dev 에서 확인만 하고 안 올리면 내 서버에만 남습니다. 커밋·푸시까지 해야 한 바퀴가 끝납니다.

• 핵심 정리: 스펙 → 생성 → 스펙 넣기 → 첫 기능 → 커밋·푸시. 새 프로젝트를 맡았을 때의 전체 흐름을 스스로 돌았습니다.
• 다음 시간: 이번엔 남이 만들어 둔 기존 프로젝트에 합류해 개선합니다.

앞에서는 프로젝트를 처음부터 만들었습니다. 실무는 대부분 남이 이미 만들어 둔 프로젝트에 합류해 고치는 일입니다.

• 대상: 실제 사내 프로젝트 popax (내가 만든 게 아니라, 이미 돌아가고 있는 남의 프로젝트)
• 흐름: 가져오기 → 파악 → 작은 개선 → 커밋·푸시
• 여기서 넣는 개선은 실제 popax 에 남습니다. 온보딩을 거치는 동안 popax 는 조금씩 나아집니다.

devtools 런처에서 남의 저장소를 내 서버로 가져옵니다. (참고: CHAP.02 프로젝트 다루기 - L03 프로젝트 가져오기)

# 🖥️ 서버 터미널
gildong@ip-172-31-39-132:~$ cd ~/standarda-devtools
gildong@ip-172-31-39-132:~/standarda-devtools$ claude

clone-repo 로 https://github.com/popupstudio-ai/popax.git 셋업해줘

/exit

• 결과물은 ~/popax/src 에 준비됩니다.
• 데이터베이스·.env 가 더 필요하면 Claude Code 가 안내해 줍니다. 안내대로 따르면 됩니다.

프로젝트 안에서 개발 서버를 켜고, 어떤 프로젝트인지 눈으로 파악합니다.

# 🖥️ 서버 터미널
gildong@ip-172-31-39-132:~$ cd ~/popax/src
gildong@ip-172-31-39-132:~/popax/src$ claude

개발 서버 띄워줘

• 안내된 dev 주소가 열리면, 화면을 몇 개 눌러보며 무엇을 하는 프로젝트인지 파악합니다.
• 코드를 다 이해할 필요는 없습니다. "어떤 기능이 있는지" 감을 잡는 정도면 됩니다.

같은 프로젝트 세션에서 작은 변경을 요청합니다. 남의 코드이니, 처음부터 큰 걸 건드리지 않습니다.

메인 화면 제목 옆에 짧은 안내 문구 한 줄을 추가해줘

• 중간에 나오는 계획과 스펙 확인에 답합니다.
• 무엇을 바꿀지 막연하면, 어디에 무엇이 보이면 되는지 한 문장으로 적어 줍니다.
• 끝나면 dev 주소에서 바뀐 화면을 확인합니다.

개선을 실제 popax 에 반영합니다. 올리는 방식은 프로젝트의 팀 정책을 따릅니다.

• popax 는 보호된 저장소가 아니라 master 에 직접 올려도 되는 프로젝트입니다.
  • 참고: PR(리뷰 요청)이 꼭 필요한 곳은 공용 패키지(standarda-core·standarda-template) 뿐입니다.

지금까지 변경한 내용을 깃허브에 올려줘

• 올리기 전에 다른 사람의 최신 변경이 있을 수 있습니다. 충돌이 나도 직접 손대지 말고 "충돌 해결해줘" 라고 하면 Claude Code 가 정리해 줍니다.

• GitHub 저장소(https://github.com/popupstudio-ai/popax)의 최근 변경 목록에 방금 올린 개선이 보이면 성공입니다.
• 남이 만든 프로젝트에 내 개선이 실제로 들어간 것입니다.

• 핵심 정리: 남이 만들어 둔 실제 popax 를 가져와(가져오기 → 파악 → 작은 개선 → 커밋·푸시) 실제 코드에 기여했습니다. 기존 프로젝트에 합류했을 때의 기본 흐름입니다.
• 주의 사항: 남의 코드는 처음부터 크게 바꾸려 하지 않습니다. 작은 변경 하나로 흐름을 익힙니다. 올리는 방식은 프로젝트마다 다르니 팀 정책(직접 push 인지 PR 인지)을 먼저 확인합니다.
• 다음 시간: 온보딩을 마쳤습니다. 더 깊은 원리와 응용은 세션에서 이어집니다.
• 참고: standarda 가 내부적으로 어떻게 구성되는지(core·template·devtools)는 상단 제품 소개 → standarda 생태계 메뉴에서 볼 수 있습니다.