[5편] 블로그용 지침서는 홈페이지 개발에 못 씁니다
카테고리: AI 기반 개발 / 개발 방법론 태그: 개발방법론, 문서구조, 템플릿, 재사용, 1인개발, 지식관리 시리즈: 도구 열 개를 정리하고 방법론 하나를 남겼다 (5/8)
정리를 끝내고 며칠 뒤
4편에서 문서를 6개로 깔끔하게 정리했습니다.
docs/
├── agent.md ← 작업 지침
├── system.md ← 시스템 구조
├── design.md ← UI 디자인
├── manual.md ← 운영 매뉴얼
├── changelog.md ← 작업 이력
└── todo.md ← 작업 목록뿌듯했습니다. 그런데 이런 생각이 들었습니다.
"이거 다음 프로젝트에서 쓸 수 있나?"
agent.md를 열어봤습니다.
스택: PHP + MariaDB(PDO)
관리자: admin/*.php (29개)
API: api/*.php (20개)
테마: themes/{pro,shop,startup,home} 기본 pro
건드리면 안 되는 것:
- 음성 입력 continuous = true (false면 첫 문장 후 종료)
- .badge 의 white-space: nowrap (없으면 글자가 세로로 쪼개짐)
- nav_svg() 정의 위치는 _header.php홈페이지 개발할 때 아무 쓸모가 없습니다.
admin/*.php 29개? 홈페이지엔 그런 거 없습니다.
음성 입력 continuous? 영상 자동화 시스템에 그게 왜 있습니까.
정리를 잘 한 게 아니라, 잘 정리된 블로그 전용 문서를 만든 거였습니다.
문제를 정확히 짚으면
agent.md 안에 성격이 다른 두 종류가 섞여 있었습니다.
━━━ 종류 A: 어떤 프로젝트든 똑같은 것 ━━━
- 백업하고 고친다
- 문법 검사 → 실제 검증 → 문서 갱신
- 경계면 교차 확인
- 역할별 렌즈 4개
- 검사 도구를 믿기 전에 검사 도구를 검사한다
━━━ 종류 B: 이 프로젝트에서만 맞는 것 ━━━
- PHP + MariaDB
- admin 29개, api 20개
- themes/{pro,shop,startup,home}
- 음성 입력 continuous = true
- .badge nowrapA는 평생 씁니다. B는 이 프로젝트가 끝나면 버립니다.
그런데 한 파일에 같이 있습니다. 그래서 다음 프로젝트를 시작하면 A까지 같이 버려집니다.
이게 지금까지 매번 처음부터 시작했던 이유였습니다. 방법론이 없었던 게 아니라, 방법론이 프로젝트에 묶여 있었습니다.
그래서 3계층으로 나눴습니다
┌──────────────────────────────────────────────────────┐
│ Layer 0 · 범용 방법론 코어 │
│ dev-core/method.md │
│ "프로젝트 종류와 무관하게 항상 같은 것" │
│ → 2단 루프 · 완료 조건 · 역할별 렌즈 · 경계면 QA │
└───────────────────────┬──────────────────────────────┘
│ 참조 (복사 아님)
┌───────────────┼───────────────┬──────────────┐
▼ ▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
│ Layer 1 │ │ Layer 1 │ │ Layer 1 │ │ Layer 1 │
│ 블로그 │ │ 홈페이지 │ │ 영상자동화 │ │ 마케팅 │
│ 템플릿 │ │ 템플릿 │ │ 템플릿 │ │ 템플릿 │
└────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘
│ 복사 │ │ │
▼ ▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
│ Layer 2 │ │ Layer 2 │ │ Layer 2 │ │ Layer 2 │
│ 실제 │ │ 실제 │ │ 실제 │ │ 실제 │
│ 프로젝트 │ │ 프로젝트 │ │ 프로젝트 │ │ 프로젝트 │
└──────────┘ └──────────┘ └──────────┘ └──────────┘| 계층 | 위치 | 내용 | 갱신 시점 |
|---|---|---|---|
| Layer 0 | dev-core/method.md |
범용 방법론 | 프로젝트 종료 회고 시 |
| Layer 0 | dev-core/learnings/ |
프로젝트별 회고 | 프로젝트 종료 시 1회 |
| Layer 1 | dev-core/templates/{도메인}/ |
도메인별 문서 뼈대 | 해당 도메인 종료 시 |
| Layer 2 | 실제 프로젝트 폴더 | 코드 + 채운 docs/ | 작업할 때마다 |
여기서 4편의 교훈이 다시 나옵니다
4편에서 "복사하면 반드시 갈라진다"고 했죠.
이 구조가 바로 그 함정에 빠지기 딱 좋습니다.
Layer 0의 method.md를 각 프로젝트에 복사해두면 편합니다.
프로젝트 폴더만 열면 다 보이니까요.
그런데 그러면 6개월 뒤에 method.md가 다섯 개 생기고, 전부 다릅니다. 4편의 그 사고가 방법론 단위로 재현되는 겁니다.
그래서 규칙을 못 박았습니다.
코어는 Layer 0 한 곳에서만 진화한다. 프로젝트는 참조만 한다.
프로젝트 docs/agent.md 맨 위에는 이 한 줄만 둡니다.
> 방법론 코어: `dev-core/method.md` 참조.
> 이 문서는 이 프로젝트 고유 내용만 담는다.내용을 복사하지 않습니다. 위치만 가리킵니다.
실제로 뽑아낸 것
블로그 agent.md(약 11KB)에서 프로젝트 무관한 것만 골라
method.md(약 12KB)를 만들었습니다.
뽑은 것 (Layer 0으로 승격)
| 항목 | 내용 |
|---|---|
| 2단 개발 루프 | 준비 → 큰 루프(전체 구현) → 작은 루프(섹션별 완성) |
| 매 작업 공통 순서 | 요청 재정의 → 소스 확인 → 백업 → 최소 수정 → 검증 → 문서 |
| 역할별 렌즈 | 개발 / QA / 보안 / 최적화 (3편) |
| 완료 조건 10항 | 문법·동작·DB·노출·최적화·경계면·헤더·위치·문서·모순 |
| 경계면 교차 확인 | 존재가 아니라 일치를 본다 (3편) |
| 검사 도구 불신 규칙 | 검사기를 믿기 전에 검사기를 검사한다 |
| 보안·백업·문서 규칙 | 키 노출 금지, 백업 위치, 문서 5원칙 (4편) |
| 파일 헤더 규칙 | [DEV_MAP] 마커 표준 |
| 새 도구 30분 평가 틀 | (3편) |
| 학습 시스템 | 회고 → 반영 → 템플릿 승격 (8편) |
남긴 것 (Layer 1에 그대로)
PHP + MariaDB(PDO)
admin/*.php 29개 · api/*.php 20개
themes/{pro,shop,startup,home}
음성 입력 continuous = true
.badge 의 white-space: nowrap
nav_svg() 는 _header.php 에 정의
판별 기준은 질문 하나입니다
각 항목을 놓고 이것만 물으면 됩니다.
"영상 자동화 시스템을 만들 때도 이 문장이 필요한가?"
- 필요하다 → Layer 0 (
method.md) - 필요 없다 → Layer 1 (
templates/{도메인}/)
"백업하고 고친다"는 영상 자동화에도 필요합니다. → Layer 0
".badge에 nowrap"은 영상 자동화에 없습니다. → Layer 1
애매한 게 별로 없습니다. 대부분 5초 안에 갈립니다.
새 프로젝트는 이렇게 시작합니다
# 1. 도메인 템플릿 복사
cp -r dev-core/templates/homepage-general/ ./new-project/
# 2. docs/agent.md 상단 포인터 확인
# "> 방법론 코어: dev-core/method.md 참조"
# 3. 기획 → 프로세스 → 재료 준비 → MVP
# 4. 개발 (큰 루프 → 작은 루프)
# 5. 종료 시 회고 → learnings/ 기록 → method.md 갱신핵심은 2번입니다.
새 프로젝트를 시작해도 완료 조건 10개, 역할별 렌즈 4개, 경계면 QA가 이미 준비돼 있습니다. 다시 만들 필요가 없습니다.
새로 채우는 건 그 도메인의 고유한 것들뿐입니다. 스택이 뭔지, 파일 구조가 어떤지, 뭘 건드리면 안 되는지.
도메인 목록
| 도메인 | 템플릿 | 상태 |
|---|---|---|
| 블로그 시스템 | templates/blog-system/ |
1차 완료 |
| 홈페이지 개발 | templates/homepage-general/ |
예정 |
| AI 콘텐츠 자동화 | templates/content-automation/ |
예정 |
| 영상 자동화 | templates/video-automation/ |
예정 |
| 업무 자동화 | templates/work-automation/ |
예정 |
| 마케팅 분석·도구 | templates/marketing-tools/ |
예정 |
지금은 하나뿐입니다. 그래도 됩니다.
한꺼번에 여섯 개를 만들면 그건 상상으로 만든 뼈대입니다. 그 프로젝트를 해본 적이 없으니까요.
해본 도메인만 템플릿이 생깁니다. 안 해본 도메인은 목록에 이름만 있으면 됩니다.
남는 이야기
첫째, "잘 정리했다"와 "재사용 가능하다"는 다릅니다.
문서를 6개로 줄이고 중복을 없앤 건 잘한 일입니다. 그런데 그 6개가 전부 한 프로젝트에 묶여 있으면, 다음 프로젝트에선 0개에서 다시 시작합니다.
정리했으면 그다음 질문은 "이거 다음에도 쓰나?" 입니다.
둘째, 판별 기준은 하나면 충분합니다.
"영상 자동화에도 이 문장이 필요한가?" 질문 하나로 11KB짜리 문서가 범용과 전용으로 갈렸습니다.
복잡한 분류 체계가 필요 없습니다. 전혀 다른 프로젝트를 하나 떠올리고, 거기서도 필요한지 물으면 됩니다.
셋째, 계층을 나눴으면 참조로 연결해야 합니다.
계층만 나누고 내용을 복사해두면 4편의 사고가 그대로 재현됩니다. 그것도 이번엔 방법론 단위로 갈라집니다.
코어는 한 곳에서만 진화하고, 나머지는 위치만 가리킵니다.
여기까지가 계획대로 된 부분입니다.
그다음 날, 디자인 도구를 하나 테스트하다가 이 방법론이 제대로 시험대에 올랐습니다.
6편에서 그 이야기를 하겠습니다.
이전 편: [4편] 공식 하나를 세 군데에 복사했다가 전부 틀렸습니다 다음 편: [6편] 설치 로그가 거짓말을 했습니다
이 글은 프로젝트 전용 문서에서 범용 방법론을 분리한 기록입니다.
결과: agent.md 11KB에서 범용 부분을 분리해 method.md 12KB 생성
댓글 0