코딩 에이전트 체크리스트: Claude Code ver.

* AI 코딩 에이전트 사내 밋업
* 2025년 7월 10일

Transcript

1. 코딩 에이전트 체크리스트 Claude Code ver. @nacyotkim @nacyotkim 1
2. 코딩 에이전트를 바라보는 시선 @nacyotkim 2
3. @nacyotkim 3
4. 어디 한 번 잘 하나보자? @nacyotkim 4
5. 어디 한 번 잘 하나보자? @nacyotkim 5
6. 어떻게 도와줄 수 있을까? @nacyotkim 6
7. @nacyotkim 7
8. 코딩 에이전트가 문제를 풀기 위해서 필요한 것 개발 환경과 컨텍스트 @nacyotkim 8
9. 왜 내 에이전트는 스스로 동작하지 않나요? @nacyotkim 9
10. 스스로 동작하기 위해서는 피드백 루프 안에서 탐색하고, 실패할 수 있어야한다 @nacyotkim 10
11. 개발 환경 @nacyotkim 11
12. @nacyotkim 12
13. 대규모 컨텍스트 @nacyotkim 13
14. @nacyotkim 14
15. @nacyotkim 15
16. 당신의 코딩 에이전트는 "좋은 환경"에서 일하고 있나요? @nacyotkim 16
17. 조엘 테스트 @nacyotkim 17
18. 조엘 테스트(2000) @nacyotkim 18
19. 1. 소스코드 관리시스템을 사용하고 있습니까? (지금은 당연한, GitHub DEEF년) 2. 한방에 빌드를 만들어낼 수 있습니까? 3. 일일 빌드를 하고 있습니까? 4. 버그 추적시스템을 운영하고 있습니까? 5. 코드를 새로 작성하기 전에 버그를 수정합니까? 6. 일정을 업데이트하고 있습니까? 7. 명세서를 작성하고 있습니까? 8. 조용한 작업 환경에서 일하고 있습니까? 9. 경제적인 범위 내에서 최고 성능의 도구를 사용하고 있습니까? 10. 테스터를 별도로 두고 있습니까? 11. 프로그래머 채용 인터뷰 때 코딩 테스트를 합니까? 12. 무작위 사용편의성 테스트를 수행하고 있습니까? @nacyotkim 19
20. 코딩 에이전트 체크리스트 Claude Code ver. @nacyotkim 20
21. 1. 에이전트로서 일을 맡기고 있나요? 2. 신규입사자 가이드가 있나요? 3. 프로젝트 기여를 위한 룰을 가지고 있나요? 4. 잘 갖춰진 커맨드라인 환경을 제공하나요? 5. 테스트를 하고 있나요? 6. 브라우저 테스트를 하고 있나요? Y. Ultrathink하고 있나요? c. Hook을 활용하고 있나요? 9. 커스텀 커맨드를 사용하고 있나요? jk. CI를 사용하고 있나요? 11. 이슈 관리와 PR을 통해 협업하고 있나요? jx. git worktree를 사용하고 있나요? @nacyotkim 21
22. 1. 에이전트로서 일을 맡기고 있나요? @nacyotkim 22
23. 1. 에이전트로서 일을 맡기고 있나요? • 내 일을 도와주는 게 아니라, 일을 직접 하는 에이전트. • 신뢰관계를 구축하는 시간이 필요함 • 아주 쉽고 짧은 작업부터 • README 수정, 오타 고치기, 프로젝트 분석 • 어렵고 긴 작업까지 확장해나가기 • 대규모 리팩토링, 기능 해결, 어려운 이슈 디버깅. • 이제 사람의 역할은? 계획, 코드 리뷰, QA, 환경 관리, 책임 등 @nacyotkim 23
24. 2. 신규입사자 가이드가 있나요? @nacyotkim 24
25. 2. 신규입사자 가이드가 있나요? • 소프트랜딩을 위한 필수 문서 • 매 세션마다 소프트랜딩이 필수적으로 이루어짐 • /clear • Rule에서도 가장 앞에 배치를 추천합니다 • 최대한 많이 탐색하고 작업하도록 가이드 • LLM은 아무것도 기억하지 못 함 @nacyotkim 25
26. 3. 프로젝트 기여를 위한 룰을 가지고 있나요? @nacyotkim 26
27. 3. 프로젝트 기여를 위한 룰을 가지고 있나요? • CLAUDE.md 룰 파일은 권장이 아니라 필수 • 프로젝트 개요와 현재 팀에서 공유하는 개발 원칙은 반드시 공유되어야함 • 개발에 활용하는 도구가 있다면 적극적으로 알려주세요 • 무조건 길거나 문서화 되어있다고 좋은 건 아님 @nacyotkim 27
28. @nacyotkim 28
29. 반복보다 강조 반복보다 강조 반복보다 강조 @nacyotkim 29
30. 4. 잘 갖춰진 커맨드라인 환경을 제공하나요? @nacyotkim 30
31. 4. 잘 갖춰진 커맨드라인 환경을 제공하나요? • LLM의 주특기: 커맨드라인, Bash 셸 스크립팅 • 특히 1회성 셸 스크립팅 천재(!) • GitHub MCP 없어도 gh 명령어를 매우 잘 활용함 • 터미널의 가능성 X LLM의 터미널 활용 능력 @nacyotkim 31
32. 5. 테스트를 하고 있나요? @nacyotkim 32
33. 5. 테스트를 하고 있나요? • 스스로 문제를 해결하는 피드백 루프의 핵심은 테스트 • 문제를 해결했는지, 실패했는지 명확한 피드백을 전달 • 테스트도 에이전트가 짜고, 스스로 루프에 갇힘(!) • 가끔 풀다가 포기함 • "못 풀었다" 보고, 주석 처리, 테스트 삭제, 조작(!) • 기능 테스트 필수 / 회귀 테스트 권장 @nacyotkim 33
34. 6. 브라우저 테스트를 하고 있나요? @nacyotkim 34
35. 6. 브라우저 테스트를 하고 있나요? • 웹개발: 브라우저 테스트로 UI를 피드백 루프에 집어넣기 • Claude Code는 이미지 파일을 실행중에 읽어올 수 있음 • Playwright 사용한 스크린샷 • 네트워크 호출 내역, JavaScript 디버깅 정보 등을 STDOUT으로 제공 • 어떻게 문제를 텍스트와 이미지로 전달할 것인가? @nacyotkim 35
36. !. Ultrathink하고 있나요? @nacyotkim 36
37. @nacyotkim 37
38. !. Ultrathink하고 있나요? • 매직 키워드 • think: ./// • metathink: 3//// • ultrathink: 73888 • 최대 토큰 수(20만)에서 추론 토큰 수를 미리 점유하는 방식 • 환경변수로도 설정 가능 • MAX_THINKING_TOKENS=15000 • 10000 ~ 20000정도를 추천 @nacyotkim 38
39. !. Hook을 활용하고 있나요? @nacyotkim 39
40. !. Hook을 활용하고 있나요? • Hook은 단순 자동화가 아닌 반자율주행 알고리즘 주입 • PreToolUse: 툴을 사용하기 전 • PostToolUse: 툴을 사용한 다음(LLM에 전송 전) • Notification: 알림 발생 시점 • Stop: 작업 종료시 • 예: 작업 종료 후 회귀 테스트 실행 •회귀 테스트 실패하면 디버깅 메시지 전달 • SubagentStop: 서브 에이전트 작업 종료시 @nacyotkim 40
41. 작업 종료하면 회귀 테스트 실패하면 디버깅 @nacyotkim 41
42. { "hooks": { "Stop": [ { "matcher": "", "hooks": [ { "type": "command", "command": "./.claude/hooks/10_stop__rspec.rb", "timeout": 600 } ] } ] } } @nacyotkim 42
43. 9. 커스텀 커맨드를 사용하고 있나요? @nacyotkim 43
44. 9. 커스텀 커맨드를 사용하고 있나요? • 룰에 아무리 써도 사실 잘 따르지 않음 • 프롬프트들 중에서, 사용자 프롬프트가 가장 영향력이 강함 • 예) 룰에 있지만, 한번 더 강조: "개발 가이드라인에 계획을 세워주세요" • 예) 역시 룰에 있지만, "실패하는 테스트는 한 번에 하나씩만 문제를 해결해야합니다." • $ARGUMENTS로 인자를 받아서 처리 가능 @nacyotkim 44
45. ~/.claude/commands/issue.md ૑Әࠗఠ GitHub ੉गܳ ੘ࢿ೧ঠ೤פ׮. GitHub ੉गח ׮਺ ղਊী ٮۄ ੘ࢿ೤פ׮. - GitHub ੘স਷ gh ݺ۸যܳ ୭؀ೠ ഝਊ೤פ׮. - ݢ੷ ੘স ղਊਸ ഛੋೞҊ, ҙ۲ػ ੉गա PR ੓ח૑ ଺ইࠇפ׮. ୭Ӕ ੉ग, ઁݾ ਤ઱۽ ఐ࢝೤פ׮. - GitHub ੉गܳ ੘ࢿೞӝ ੹ী ੘স ղਊਸ ୽࠙൤ Ѩష೧ঠ೤פ׮. - ੉ ղਊਸ ߄ఔਵ۽ അ੤ ௏٘ ߬੉झ੄ ௏٘ܳ ఐ࢝೤פ׮. ӒܻҊ ੘স ҅ദਸ ࣁ਒פ׮. - ੘স ҅ദীח ҙ۲ػ ౵ੌ ݾ۾੉ ನೣغযঠೞݴ, ѐߊ о੉٘ۄੋী ٮۄ ੘ࢿغযঠ೤פ׮. - ੘স ղਊҗ ҅ദਸ ߄ఔਵ۽ ࢚ࣁೠ ੉गܳ ੘ࢿ೤פ׮. - ۽ஸ ѐߊ ജ҃ਸ ഝਊೞغ, ੉गܳ ࢤࢿೞӝ ਤ೧ పझ౟ೞѢա ಞ૘ೠ ղਊ਷ ੹ࠗ ୡӝച೤פ׮. - **઺ਃ:** ௏٘ܳ ఐ࢝ೞݶࢲ അ੤ ੘সҗ ޖҙೠ ઺ਃೠ ߡӒա ޙઁܳ ߊѼ೮׮ݶ, ߹ب੄ ੉ग۽ ٟ݅פ׮. ੘স ղਊ: `$ARGUMENTS` @nacyotkim 45
46. !". CI를 사용하고 있나요? @nacyotkim 46
47. !". CI를 사용하고 있나요? • GitHub Action - claude-code-action 공식 action • 리모트 에이전트도 "개발 환경"을 챙겨야함. • 백그라운드 DB, 테스트 실행 환경, Playwright 미리 준비 @nacyotkim 47
48. @nacyotkim 48
49. 11. 이슈 관리와 PR을 통해 협업하고 있나요? @nacyotkim 49
50. 11. 이슈 관리와 PR을 통해 협업하고 있나요? • 사람간의 협업을 넘어 에이전트의 작업을 공유하는 공간 • 팀 전체가 작업 내용을 공유할 수 있고, Claude Code를 실행 가능 • 에이전트가 기존 이슈나 PR을 참고해서 작업할 수 있음 @nacyotkim 50
51. !". git worktree를 사용하고 있나요? @nacyotkim 51
52. !". git worktree를 사용하고 있나요? • Claude 공식 가이드, git에 이런 명령어가? • 하나의 저장소를 브랜치 별로 나눠서 사용 • 병렬로 사용하려면 브랜치 별로 작업 환경을 구축이 필요 • 저장소 단위로 한방 셋업을 할 수 있으면 매우 편리함 • 반드시 병렬 작업을 위한 것만은 아님(다중 컨텍스트 유지) • stash나 임시 커밋보다 온전히 컨텍스트 보존 가능 @nacyotkim 52
53. Why? 에이전트의 능력은 환경에 따라 크게 달라짐 @nacyotkim 53
54. ✅ 체크리스트 @nacyotkim 54
55. 1. 에이전트로서 일을 맡기고 있나요? 2. 신규입사자 가이드가 있나요? 3. 프로젝트 기여를 위한 룰을 가지고 있나요? 4. 잘 갖춰진 커맨드라인 환경을 제공하나요? 5. 테스트를 하고 있나요? 6. 브라우저 테스트를 하고 있나요? Y. Ultrathink하고 있나요? c. Hook을 활용하고 있나요? 9. 커스텀 커맨드를 사용하고 있나요? jk. CI를 사용하고 있나요? 11. 이슈 관리와 PR을 통해 협업하고 있나요? jx. git worktree를 사용하고 있나요? @nacyotkim 55
56. 셀프 테스트 @nacyotkim 56
57. !. ✅ 에이전트로서 일을 맡기고 있나요? 3. " 신규입사자 가이드가 있나요? ;. ✅ 프로젝트 기여를 위한 룰을 가지고 있나요? D. ✅ 잘 갖춰진 커맨드라인 환경을 제공하나요? R. ✅ 테스트를 하고 있나요? U. ✅ 브라우저 테스트를 하고 있나요? Y. ✅ Ultrathink하고 있나요? c. ✅ Hook을 활용하고 있나요? h. " 커스텀 커맨드를 사용하고 있나요? !j. ✅ CI를 사용하고 있나요? !!. " 이슈 관리와 PR을 통해 협업하고 있나요? !3. " git worktree를 사용하고 있나요? @nacyotkim 57
58. 다시, 코딩 에이전트를 바라보는 시선 @nacyotkim 58
59. 코딩 에이전트가 문제를 못 풀 때 @nacyotkim 59
60. 1. 에이 지금은 이게 한계야 @nacyotkim 60
61. 2. 어떻게 하면 이 문제(A)를 풀 수 있을 @nacyotkim 61
62. 끝까지 밀어붙이기 • 풀어낸다면 교훈정리 • 문제를 못 풀면 더 좋음. 왜 못 풀지? • 못 풀어낸다면 교훈 정리 and 직접 디버깅 해보기 @nacyotkim 62
63. 애자일 이야기: 복리의 비밀 @nacyotkim 63
64. 더글라스 엥겔바트의 작업 구분 A 작업은 원래 그 조직이 하기로 되어 있는 일을 하는 걸 말합니다. 자동차 공장이면 자동차를 만드는 것이 A 작업이 되겠죠. B 작업은 A 작업을 개선하는 걸 말합니다. 제품을 만드는 싸이클에서 시간과 품질을 개선하는 것이죠. 제품 을 만드는 시스템을 잘 설계하는 것도 포함되겠죠. C 작업은 B 작업을 개선하는 것입니다. 개선 싸이클의 시간과 품질을 개선하는 것입니다. 개선하는 인프라 스트럭춰를 설계하는 것이 포함될 것입니다. 한마디로 개선하는 능력을 개선하는 걸 말합니다. @nacyotkim 64
65. 메타적인 문제 해결(개선, B or C) • 프롬프트 이렇게 줬으면 문제를 풀었을까? • 이 테스트가 있었다면 의도대로 풀었을까? • 이 파일을 읽었다면 잘 했을까? • 이 명령어를 활용했다면, 한 방에 됐을 텐데? • 문제를 어떻게 나눠야 더 문제를 잘 풀까? • 작업 교훈을 정리하고, 잘 통하는 방법을 다시 프로젝트에 내제화 @nacyotkim 65
66. 이터레이션을 통한 개선(발전) • 끊임없는 룰 파일 개선 • 암묵지를 노출하고 쌓아나가기 • 도구/LLM 모델 자체가 일을 잘하는 게 아님 • 잘 갖춰진 환경에서, 문제를 잘 해결할 수 있음 • 체크리스트 0에서는, 정말 못 함 • 한 번에 완벽한 작업환경을 만드는 방법은 없음 @nacyotkim 66
67. 참고자료 • AI 코딩의 쓴 교훈: 왜 Claude Code와 Amp의 '막무가내 파워'가 Cursor의 '세련된 꼼수'를 압도할까? • 애자일 이야기: 복리의 비밀 • Claude Code settings - Anthropic Docs • Slash commands - Anthropic Docs • Claude Code Action - GitHub • Hooks - Anthropic Docs • Git - git-worktree Documentation @nacyotkim 67
68. 감사합니다 @nacyotkim @nacyotkim 68