[8편] 하루 만에 v1에서 v3이 됐습니다
카테고리: AI 기반 개발 / 개발 방법론 태그: 회고, 학습시스템, 개발방법론, 지식관리, 노하우축적, 1인개발 시리즈: 도구 열 개를 정리하고 방법론 하나를 남겼다 (8/8)
구조만 만들면 아무 일도 안 일어납니다
5편에서 3계층 구조를 만들었습니다.
Layer 0 dev-core/method.md 범용 방법론
Layer 1 dev-core/templates/{도메인}/ 도메인 뼈대
Layer 2 실제 프로젝트 코드 + docs여기까지 하면 뭔가 다 된 것 같습니다. 그런데 냉정하게 보면 아직 아무것도 안 자랍니다.
method.md는 만든 v1 그대로 있고,
프로젝트를 세 개 더 해도 저 파일은 그대로입니다.
고치는 시점이 정해져 있지 않기 때문입니다.
"필요하면 고치자"는 안 고친다는 뜻입니다. 개발하다 보면 눈앞의 버그가 항상 더 급하거든요.
그래서 마지막으로 만든 게 학습 시스템입니다.
규칙은 딱 하나
프로젝트가 끝나면, 반드시 회고를 쓰고 코어에 반영한다.
"끝나면"이 중요합니다. 시점이 고정돼 있어야 합니다.
- 개발 중간에 하면 → 급한 일에 밀려서 안 함
- "여유 있을 때" 하면 → 여유가 안 생김
- 프로젝트 종료 시점에 하면 → 안 하면 프로젝트가 안 끝난 것
완료 조건에 넣어버리는 겁니다. 회고를 안 썼으면 그 프로젝트는 아직 안 끝난 겁니다.
4단계로 돕니다
1단계: 회고 작성
dev-core/learnings/{날짜}_{프로젝트명}.md
# {프로젝트명} 회고
## 개요 기간 / 도메인 / 결과물
## 좋았던 점 (다음에도 그대로 할 것)
## 시행착오 (증상이 아니라 원인을 쓴다)
## 부족했던 점 (알고도 못 한 것)
## 분류
- [범용] ... → method.md N장에 반영
- [도메인] ... → templates/{도메인}/ 에 반영
- [기각] ... → 반영 안 함, 사유"증상이 아니라 원인" 이 핵심입니다.
❌ 증상: "화면이 깨졌다"
✅ 원인: "코드 검증만 하고 화면을 눈으로 안 봤다.
검증 단계에 시각 확인 항목이 아예 없었다."증상은 그 프로젝트에서만 유효합니다. 원인은 다음 프로젝트에도 그대로 적용됩니다.
2단계: 분류해서 반영
| 교훈 성격 | 반영 위치 |
|---|---|
| 모든 프로젝트에 적용됨 | method.md (Layer 0) |
| 이 도메인에서만 적용됨 | templates/{도메인}/ (Layer 1) |
| 이 프로젝트만의 특수 사정 | 반영 안 함. 회고에만 남김 |
5편의 판별 기준을 그대로 씁니다. "전혀 다른 프로젝트에서도 이게 필요한가?"
3단계: 템플릿 승격
프로젝트 docs/에서 고유값을 걷어내고 뼈대만
templates/{도메인}/로 갱신합니다. 다음에 같은 도메인을 하면 이걸 복사해 시작합니다.
4단계: 버전 기록
method.md 하단 이력 표에 한 줄 남깁니다.
출처를 적는 게 중요합니다. 6개월 뒤에 "이 규칙 왜 있지?" 싶을 때 "아 그때 그거구나" 하고 바로 알 수 있습니다. 출처를 모르면 규칙을 함부로 지우게 됩니다.
그리고 이게 하루에 두 바퀴 돌았습니다
만들어놓고 "1년 뒤에 v4쯤 되겠지" 생각했습니다. 그날 안에 v3이 됐습니다.
실제 이력 표입니다.
| 버전 | 날짜 | 추가/변경 | 출처 |
|---|---|---|---|
| v1 | 2026-07-22 | 최초 작성. 2단 루프, 완료 조건, 역할별 렌즈, 경계면 교차 확인, 검사 도구 불신 규칙, 도구 평가 틀, 학습 시스템 | 블로그 시스템 프로젝트 정리 |
| v2 | 2026-07-22 | 파일 소유권 규칙 추가 | dev-core 이전 작업 중 실제 발생 |
| v3 | 2026-07-22 | 도구 설치 위치 실측 규칙 추가 | impeccable 격리 설치 실패 |
v2가 나온 경위
방법론 파일을 서버의 제 위치로 옮기는 작업 중이었습니다.
root 권한으로 파일을 편집했더니 소유자가 root로 바뀌었습니다. 그러면 FTP로 편집이 안 됩니다.
검증 단계에서 잡아서 되돌렸는데, 생각해보니 이건 이 프로젝트만의 문제가 아니었습니다. 제 서버 구조가 어느 프로젝트든 같으니까요.
그래서 코어에 넣었습니다.
### 파일 소유권
* root 세션에서 사용자 소유 파일을 편집하면 소유자가 root로 바뀐다.
편집 직후 원래 소유자로 되돌린다. 안 되돌리면 FTP 편집이 막힌다.
* 완료 조건에 "편집한 파일의 소유자·권한이 편집 전과 같은가" 를 추가한다.웃긴 건, 이 규칙을 문서에 적는 그 편집 때문에 파일 세 개가 또 root로 튀었습니다. 그리고 방금 만든 그 규칙 때문에 바로 복구됐습니다.
규칙이 만들어지자마자 자기 자신을 잡았습니다.
v3이 나온 경위
6편의 그 사건입니다.
도구가 "project 스코프에 설치했다"고 로그를 찍고 전역에 설치했습니다. 그래서 도구 평가 틀에 항목을 하나 추가했습니다.
5. 설치 후 실제 설치 위치를 직접 확인한다.
도구의 설치 로그를 믿지 마라. "project 스코프로 설치했다"고
찍고서 전역에 설치한 사례가 있다.원래 이 문서에는 "검사 도구를 믿기 전에 검사 도구를 검사한다"가 있었습니다. 그게 설치 도구까지 확장된 겁니다.
두 번 다 "실제로 당한 것"입니다
v2도 v3도 제가 상상해서 넣은 게 아닙니다. 그날 실제로 겪은 일입니다.
이게 중요합니다. 방법론 문서가 죽는 가장 흔한 이유가 "좋아 보이는 규칙"을 미리 잔뜩 적어놓는 것이거든요.
겪지 않은 규칙은 안 지킵니다. 왜 있는지 모르니까요. 겪은 규칙은 지킵니다. 아팠으니까요.
그래서 이 문서는 아플 때만 자랍니다.
열 개의 도구가 남긴 것
1편에서 AI 도구가 열 개라고 했습니다. 하루가 지나고 정리하니 이렇게 됐습니다.
| 도구 | 결과 |
|---|---|
| harness | 관점 3개 흡수 후 폐기 |
| impeccable | 지식 10.6KB 추출 후 완전 제거 |
| Hermes | 설치 상태 유지. 아직 안 씀 |
| 나머지 | 정리 대상 |
실제로 남은 건 도구가 아니라 파일 세 개입니다.
method.md v3, 12KB 범용 방법론
learnings/{날짜}_{프로젝트}.md 프로젝트 회고
design-notes/impeccable-extract.md 디자인 지식도구는 버전이 올라가고 유지보수가 끊깁니다. 이 세 개는 안 낡습니다.
언제 코어를 고쳐야 하는지
회고 때 말고도 손봐야 할 신호가 있습니다.
① 같은 유형의 문제가 2회 이상 반복될 때
→ 우연이 아니라 방법론에 구멍이 있는 것
② 같은 실수를 다시 했을 때
→ "알고 있었는데 또 그랬다" = 체크리스트에 없다는 뜻
③ 문서를 무시하고 감으로 작업하고 있을 때
→ 문서가 현실과 안 맞는다는 신호특히 ③번입니다.
문서를 안 보게 되면 보통 "내가 게을러서"라고 생각합니다. 대부분은 문서가 실제 작업과 안 맞아서입니다.
안 보게 된 문서는 게으름의 증거가 아니라 고칠 곳의 표지판입니다.
시리즈를 정리하면
1편 도구 10개를 깔아놓고 하나도 제대로 안 쓰고 있었다
2편 harness와 Hermes를 같은 거라고 믿었다
3편 30분만 열어보기로 했다 → 흡수 3, 기각 4
4편 공식을 세 군데 복사했다가 전부 틀렸다 → 문서 6개로 단일화
5편 블로그용 지침서는 홈페이지에 못 쓴다 → 3계층 분리
6편 설치 로그가 거짓말을 했다 → 격리 규칙이 값을 함
7편 도구는 버리고 지식만 뽑았다 → register 구분 발견
8편 하루 만에 v1에서 v3이 됐다 → 학습 루프 확인시작은 "헤르메스가 요즘 뜬다더라" 였습니다. 그리고 정작 그 헤르메스는 아직 안 써봤습니다.
끝난 자리에 남은 건 도구가 아니라 제 방법론 문서 한 개입니다.
남는 이야기
첫째, 회고 시점을 고정하지 않으면 회고는 안 합니다.
"나중에", "여유 있을 때", "필요하면"은 전부 안 한다는 뜻입니다. 완료 조건에 넣어야 합니다.
둘째, 증상 말고 원인을 적으세요.
"화면이 깨졌다"는 그 프로젝트에서만 유효합니다. "검증 단계에 시각 확인 항목이 없었다"는 평생 씁니다.
회고를 쓰다가 "이거 다른 프로젝트에서도 일어날까?"를 물으면 증상인지 원인인지 바로 갈립니다.
셋째, 축적되는 건 코드가 아니라 판단 기준입니다.
3년치 코드가 쌓여 있어도 다음 프로젝트에 그대로 쓸 건 별로 없습니다. 스택이 바뀌고 요구사항이 바뀌니까요.
그런데 "경계면부터 본다", "검사기를 먼저 검증한다", "설치 위치를 실측한다" 같은 판단 기준은 안 낡습니다. 언어가 바뀌어도, 프레임워크가 바뀌어도, AI 도구가 바뀌어도 그대로 씁니다.
도구를 열 개 깔면서 배운 건 하나입니다.
쌓아야 할 건 도구가 아니라 이겁니다.
이전 편: [7편] 도구는 버리고 지식만 뽑아냈습니다
이 시리즈는 2026년 7월 21~22일, 실제 하루의 기록입니다.
산출물: method.md v3 · 프로젝트 회고 1건 · 디자인 추출 노트 1건 · 제거된 도구 2개
댓글 0