블로그 리노베이션 – 시작은 작게

블로그를 내 취향에 맞게 만들기 시작했다. 사람들에게 바이브의 중요성, 에이전틱 개발을 잘 해야한다고 이야기만 했었다. 샘플 코드야 몇 번 보여주기 위해 작성한 적은 있지만 실제로 돌아가는 쓰이는 코드를 작성한 건 정말 몇 년 된 것 같다. 그래도 왕년에는 개발 좀 했다고 생각을 했던 사람이라 이제 몸을 풀 수 있는 시간이 생겼으니 한번 제대로 풀어볼 계획이다. 개발할 때 가장 재미있는 순간은 내가 만든 걸 누군가가 쓸 때다. 이 블로그는 7~8년 내가 간간히 글을 작성하고 사람들에게 공유했던 공간이자 시스템이다. 어찌됐던 “나” 라는 글 쓰는 사용자가 있고, 간간히 글을 봐주러 오는 글 읽는 사용자가 있는 서비스다. 사용자가 재미있게 쓸 수 있는 시스템으로 다시 한번 리노베이션 할 계획이다. 다만 바이브로. 손 코딩을 얼마나 더할 수 있을 지 모르겠지만, 대부분의 코드는 클로드 코드를 사용해 작성할 예정이다.

내 손으로 하는 제대로, 처음 바이브이기 때문에 욕심낼 생각은 없다. 말은 많았지만 개발 바이브가 손에 익은 상태가 아니라 첫 걸음은 쉽게 가야한다. 급하게 서두르다가 자빠지는 건 바이브 씬에서도 마찬가지다. 목적은 마크다운(Markdown) 형식으로 글 작성하고, 이걸 편하게 읽을 수 있는 포맷으로 제공하는 것이다. 특히 AI로 피딩을 줄 때 지금의 워드프레스(WordPress) 기반은 html 기반이고, 페이지 내용을 요청했을 때 주변으로 감싸는 꾸미기 요소들이 너무 많다. 설치형으로 자체 운영하다보니 나온 사이드이펙트이기도 하다. 추가로 내가 읽은 책들을 정리할 방법도 애매했다. 이번 리노베이션 하면서 책장을 좀 짜볼 예정이다. 마지막으로 글 작성하는 스타일을 포함해 정해지지 않은 몇 가지 부분을 MCP로 제공할 예정이다. 최근에 글쓰기 작업을 하고 있는데, 내가 쓰는 글 스타일을 벗어나는 좀 재미없는 스타일이 나왔다. MCP로 AI 친구가 일관성있게 교정해주지 않을까 싶은 기대치 하나를 갖고 있다.

개발 시작은 다음 규칙으로 우선 간단히 시작하고 진행하면서 발전시켜 볼 요량이다.


# simple-blog

블로그 서비스. 백엔드와 프론트엔드를 하나의 에이전트가 함께 개발한다.

## 구조

| 경로 | 역할 | 스택 |
| --- | --- | --- |
| `be/` | 백엔드 | Spring Boot 4.1, Java 25, Gradle Wrapper |
| `fe/` | 프론트엔드 | React 19, TypeScript, Vite, npm |
| `be/apispec.yaml` | API contract | OpenAPI 3.1 |

이 루트 디렉토리가 단일 git 저장소이고, `be/`와 `fe/`는 그 안의 일반 디렉토리다.

## 작업 방식

- 단일 에이전트로 진행한다. BE와 FE 작업을 서브에이전트로 나누지 말고 직접 처리한다.
- 작업은 항상 이 루트 디렉토리에서 시작하고, 필요한 쪽의 코드를 직접 수정한다.
- 한 branch는 한 feature를 담는다.
- 하나의 기능에 대한 스펙, BE, FE 변경은 하나의 커밋에 함께 담을 수 있다.
- branch가 main에 머지되면 별도의 지시가 없다면 해당 branch는 삭제한다.

### Coding 기본 룰
- 한 라인은 150자 이하가 되도록 한다.
- 한 메소드의 Line 수는 최대 20줄이 넘지 않아야 한다.
- 메소드의 이름은 get 혹은 set으로 시작하지 않는다.
- 조회를 위한 이름은 명사 혹은 복수 항목을 조회하는 경우에는 `listOf` 를 복수형 명사의 prefix로 사용해 명명한다.
- 행동을 수행하는 경우 Action에 부합하는 동사를 사용해 명명한다.

## API contract

`be/apispec.yaml`이 BE와 FE 사이의 유일한 기준이다.

API는 HTTP Method에 따른 용도를 준용한다.
- GET: 목록을 포함한 조회
- POST: 신규 생성
- PUT: 기존 데이터 갱신
- DELETE: 삭제

API의 endpoint는 다음의 분류에 따라 sub URI를 갖는다.
-. `/public/api/v{N}/{URI}` FE와의 통신용 API
-. `/internal/api/v{N}/{URI}` 내부 확인 혹은 어드민용 API
-. `/mcp/v{N}/{URI}` MCP 용도

API를 추가하거나 변경할 때는 다음 순서를 따른다.

1. `be/apispec.yaml`을 먼저 수정한다.
2. 스펙에 맞춰 BE를 구현하고 테스트한다.
3. 스펙에 맞춰 FE를 구현하고 테스트한다.

## 완료 기준

변경 범위에 해당하는 빌드와 테스트가 통과해야 완료로 본다. API를 변경했다면 `be/apispec.yaml`, BE, FE가 서로 일치하는지도 확인한다.

ROI는 혼자 개발하는 과정에서도 중요하다. 경험치 쌓겠다고 와이프한테 등짝을 심하게 맞으면 곤란하니까 말이다. 비용 모니터링은 매일 오전 스케쥴러를 통해 전날까지 사용한 월간 비용을 산출해 Slack으로 알림 주는 방식을 쓰기로 했다. 매일 아침 슬랙 알림으로 비용 경각심과 더불어 바이브를 하겠다는 약속을 잊지 않고 있는지… 이게 더 중요한 이유인 것 같습니다.

아직 미미하지만 그럼에도 재미있게 진행하고 있습니다. ㅎㅎ

다음 번 이야기에서는 시스템 아키텍처를 소개해보겠습니다.