# Loop Engineering

> 작동 중인 프로젝트를 한 번에 한 덩어리씩 개선할 때 사용한다. 점검 → 한 가지 작업 선정 → 최소 변경 구현 → 검증 → diff 리뷰 → 작업 로그 기록의 한 사이클을 수행한다. 한 번 호출 = 한 루프 = 검증 가능한 작은 개선 하나. "다음 작업 하나만 해줘", "이어서 개선해줘", "loop 돌려줘", "뭐부터 손대면 되지", "작게 하나만 고치자" 같은 요청에 트리거된다. 요구사항이 이미 정해진 기능을 구현하는 것이 목적이면 이 Skill 이 아니라 그냥 구현한다. 변경분을 평가하는 것이 목적이면 code-review, 버그 원인 추적이면 debugging 을 쓴다.

- Skill: `j99way99/loop-engineering` (Agent Skill)
- Install (CLI): `npx skillmds@latest add j99way99/loop-engineering`
- Raw SKILL.md: https://api.skillmd.com/api/skills/j99way99/loop-engineering/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: j99way99 (https://skillmd.com/u/j99way99)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/j99way99/loop-engineering

---


# Loop Engineering

절제된 시니어 엔지니어처럼 일한다: 점검 → 계획 → 구현 → 검증 → 리뷰 → 기록 → 반복.

**앱을 다시 만드는 것이 목표가 아니다. 앱은 이미 동작한다.**
각 루프는 아무것도 깨뜨리지 않으면서 조금 더 낫게 만든다.

## Phase 0 — 컨텍스트 적재 (항상, 다른 무엇보다 먼저)

1. 프로젝트의 **작업 로그**를 읽는다. 기본 경로는 `logs/LOOPLOG.md` 이며, 현재 상태·최근 루프 기록·
   다음 루프 후보가 들어 있다. 이것이 컨텍스트를 매번 다시 유도하는 것을 대신한다.
   프로젝트에 다른 로그 규약이 있으면 그 프로젝트의 `CLAUDE.md` 를 따른다.
2. 로그가 없거나 오래됐으면 `CLAUDE.md` 와 `git log --oneline -10` 으로 대신한다.
3. **이 프로젝트에서의 첫 세션이라면** 한 루프를 통째로 파악에만 쓴다 (경로/라우트, 스키마, 주요 흐름,
   실행 명령). 배운 것을 그 루프의 기록으로 남긴다. **파악 루프에서는 코드를 고치지 않는다.**

## Phase 1 — 루프 작업 하나 선정

정확히 **하나**만 고른다. 우선순위:
1. 사용자가 명시적으로 요청한 것
2. 작업 로그의 "다음 루프 후보"
3. Phase 0 에서 직접 관찰한 것

좋은 루프 작업: 작고 · 검증 가능하고 · 위험이 낮고 · 쓸모 있고 · 리뷰하기 쉽다. 대략 **5파일 이하**.

고르지 않을 것: 전면 재작성 · 근거 없는 비즈니스 로직 변경 · 가벼운 의존성 추가 ·
대량 이름 변경 · UI + DB + 인증 + 인프라를 한 루프에 섞기.

**편집 전에 작업을 한 문장으로 말한다.** 가장 유력한 후보가 아래 Safety 에 걸리면 시작하지 말고 묻는다.

## Phase 2 — 구현

- 가장 작은 안전한 변경. 기존 관례와 기존 컴포넌트를 따른다.
- 핵심 동작을 보존한다. 관련 없는 정리 금지, 광범위한 리팩터링 금지.
- 눈에 보이는 제품 품질 개선을 우선한다.
- 프로젝트에 구현 가드나 디자인/카피 규약(스킬이든 `CLAUDE.md` 든)이 있으면 **그것을 따른다.**
  공통 Skill 은 그 규약을 대신 정하지 않는다.

## Phase 3 — 검증

변경을 덮는 **가장 좁은 검증**을 돌린다. 보통 그 프로젝트의 타입체크와 빌드 명령이며,
무엇인지는 `CLAUDE.md` 나 `package.json`(또는 그에 해당하는 것)에서 확인한다.

수동 확인은 **빌드가 잡을 수 없는 방식으로 깨질 수 있을 때만** 한다 — 흐름이 끊기거나,
쿼리가 잘못된 행을 돌려주거나, 레이아웃이 무너지는 경우.

> **방금 타이핑한 값이 곧 정답인 변경은 검증하지 않는다.**
> 색상 토큰, 여백 값, 문구 문자열에는 스크린샷도 computed style 확인도 필요 없다.
> 파일이 곧 사실이고, 결과를 들여다봐도 diff 가 이미 보여준 것 이상을 증명하지 못한다.
> 사용자가 "값만 바꿔달라"고 한 경우에는 바꾸고 멈춘다.

명령을 돌릴 수 없으면 **이유를 정확히 말하고** 사용자가 직접 실행할 명령을 준다.
**하지 않은 검증을 했다고 말하지 않는다.**

## Phase 4 — diff 리뷰

끝내기 전에 `git diff` 전체를 다시 읽고 확인한다:
- 사용자 흐름이 깨졌는가 (그 프로젝트의 핵심 흐름 — `CLAUDE.md` 가 무엇인지 말해준다)
- 의도하지 않은 비즈니스 로직 변경이 있는가
- 인증/데이터 접근 실수가 있는가 (서버 측 소유권 확인)
- UI 회귀나 모바일 레이아웃 문제가 있는가
- 타입 오류나 빌드 위험이 있는가
- 선언한 작업보다 넓게 편집했는가

여기서 걸리는 것은 고치거나 되돌린다.

더 깊은 검토가 필요하면 `code-review` 절차를 적용한다.

## Phase 5 — 기록

작업 로그의 "Loop notes" 아래(최신이 위)에 **한 덩어리**만 덧붙인다:

```
### YYYY-MM-DD · <짧은 목표>
- Files: <경로>
- Changed: <1~3줄, 무엇을 왜>
- Verified: <실행한 명령 + 결과, 또는 "manual: ...">
- Risk: <남은 위험, 또는 "none known">
- Next: <다음 루프 후보 1~2개>
```

10줄 안쪽으로 유지한다. 이번에 끝낸 항목은 "다음 루프 후보" 목록에서 뺀다.

## Safety (타협 없음)

아래는 **가볍게 하지 않는다.** 멈추고 설명한 뒤(무엇이 위험한가 / 왜 필요할 수 있는가 /
더 안전한 대안 / 권고) 사용자 승인을 기다린다:

- 핵심 비즈니스 로직 변경
- DB 스키마 또는 마이그레이션 변경
- 인증/세션 로직 변경
- 결제 관련 로직 변경
- 의존성 추가
- 기능 삭제
- 아키텍처 재작성
- 프로덕션 DB나 프로덕션 환경에 닿는 모든 것

그럴듯한 이유가 있어도 **절대** 하지 않는다:
- 자동 커밋/푸시 (사용자가 요청했을 때만)
- 파괴적 셸 명령 (`rm -rf`, `git reset --hard`, force push)
- 루프 작업과 무관한 파일 편집

## 루프마다의 출력

1. 결과 (한 줄: 무엇이 나아졌는가)
2. 변경된 파일
3. 검증 결과
4. 작업 로그에 덧붙인 기록
5. 다음 루프 제안