"feature_list.json 한 장이, 흩어진 작업을 살아 있는 뼈대로 묶습니다. 메모가 아니라 시스템입니다."

30개 항목이 전부 'In Progress'였던 화요일

지난달 어느 화요일 오후였습니다. 노션 데이터베이스를 열고, 저는 한참을 스크롤만 내렸습니다. 30개의 작업 카드가 보였고, 그중 27개의 상태 라벨이 In Progress였습니다.

AI에게 "오늘 뭐부터 할까?"라고 물었더니, AI는 30개를 모두 다시 한 줄씩 읽어 보더니 이렇게 답했습니다. "전부 진행 중으로 적혀 있어서 우선순위를 알 수 없습니다."

그 순간 깨달았습니다. AI도, 저도, 무엇이 끝났는지 모르고 있었습니다.

feature_list.json 한 장이, 흩어진 작업을 살아 있는 뼈대로 묶습니다. 메모가 아니라 시스템입니다.

사람의 메모는, AI에게 외계어입니다

노션도, Linear도, Trello도, 종이 다이어리도 사람 뇌에는 훌륭한 도구입니다. 카드를 드래그하고, 색깔로 라벨을 붙이고, 댓글로 맥락을 더합니다. 그 모든 것이 사람에게는 자연스럽게 읽힙니다.

문제는, AI는 그걸 못 읽는다는 점입니다. 정확히 말하면 읽긴 읽지만, 자기가 갱신할 수 없습니다. 노션 카드의 상태를 AI가 스스로 passing으로 바꾸지 못합니다. AI는 자기가 무엇을 끝냈는지 기록할 자리가 없습니다.

그래서 같은 작업을 두 번 합니다. 끝난 항목을 다시 손댑니다. "오늘 활성 항목이 뭔지"를 묻는 한 마디에, 30개를 처음부터 다시 훑습니다.

AI가 자기 작업 상태를 스스로 갱신할 수 있는 한 장이 필요합니다.

feature_list.json은 하네스의 뼈대입니다

사람의 메모와 feature_list.json이 다른 점은 세 가지입니다.

첫째, 검증 명령(verification command)이 박혀 있습니다. 각 항목 옆에 "이걸 어떻게 통과 여부를 확인하는가"가 한 줄로 적혀 있습니다. AI는 그 한 줄을 스스로 실행해 통과 여부를 확인합니다. 노션 카드엔 이 칸이 없습니다.

둘째, 상태(state)가 거짓말을 못 합니다. passing이라는 라벨은 검증 명령이 실제로 통과한 다음에만 붙습니다. 사람이 "다 됐겠지"라며 옮길 수 있는 칸이 아닙니다.

셋째, AI도 사람도 동시에 읽고 씁니다. 같은 파일을 사람이 열어 수정하고, AI가 다음 세션에서 그 변경을 읽습니다. 단일 진실의 원천(Single Source of Truth)이 한 곳에 있습니다.

채팅창은 휘발되고, 노션은 AI가 쓰지 못합니다. feature_list.json은 AI가 매일 출퇴근하는 작업 일지입니다.

feature_list.json 한 항목의 4칸

우리 루틴팩의 실제 구조입니다.

미니 예시는 이렇게 생겼습니다.

{
  "id": "F-003",
  "behavior": "결제 성공 시 사용자에게 영수증 이메일이 발송됩니다.",
  "verification": "테스트 결제 후 메일함에서 영수증 도착 여부와 금액 표기를 확인합니다.",
  "state": "failing",
  "owner": "agent",
  "notes": "발신 도메인 인증 미완료로 스팸함으로 분류됨."
}

네 칸이면 충분합니다. owner와 notes는 익숙해진 후에 채우셔도 됩니다.

state가 거짓말하지 않게 하는 규칙

"기능이 active에서 passing으로 이동하는 유일한 방법은, 검증 명령이 성공적으로 실행되는 것입니다."

• 검증이 통과해야만 passing. AI가 "다 된 것 같아요"라고 답해도, 그 항목은 여전히 active입니다.
• 같은 오류 3회 반복하면 failing. 막연한 진행 중이 아니라, 실패하고 있음이라고 정직하게 적습니다.
• 다른 항목에 막혀 있으면 blocked. 어떤 id 때문에 막혀 있는지 notes에 명시합니다. "F-005 검색 범위 결정 대기 중" 같은 한 줄이면 충분합니다.

state는 기분이 아니라 증거로만 움직입니다.

비개발자 사례 3개

사례 1 — 1인 빌더. 노션 데이터베이스에 흩어져 있던 feature 30개를 feature_list.json로 옮기고, 각 항목의 verification 칸을 한 줄씩 채웠습니다. 다음 세션부터 AI는 매번 이렇게 시작했습니다. "오늘 활성 항목 5개 중 3개를 끝냈고, 1개는 F-005에 막혀 있습니다." 우선순위 회의가 사라졌습니다.

사례 2 — PM. 매주 월요일 아침 30분간 직접 만들던 주간 진행 리포트가 있었습니다. feature_list.json을 도입한 뒤, AI에게 "지난주 state 변화를 표로 요약해줘" 한 줄을 시키면 리포트 초안이 나옵니다. 사람은 검토와 의사결정에만 시간을 씁니다.

사례 3 — 마케터. 콘텐츠 발행 워크플로를 feature_list.json으로 묶고, 각 발행 항목에 "실제 채널에서 게시됨"이라는 검증을 박았습니다. passing이 되어야만 다음 콘텐츠로 넘어가는 구조가 생기자, 중복 발행과 누락이 동시에 사라졌습니다.

오늘의 5분 액션

1. 우리 프로젝트의 지금 살아 있는 작업 5개를 feature_list.json에 옮깁니다. 30개는 처음부터 하지 마세요.
2. 각 항목에 verification 한 줄을 채웁니다. 자동 검증이 어렵다면 수동 절차도 OK입니다. ("메일함에서 확인"도 검증입니다.)
3. AI에게 한 번만 시켜봅니다. "이 5개의 현재 state를 점검해줘. 거짓말 가능성이 있으면 짚어줘."
4. 그 결과를 progress.md에 한 줄로 요약합니다. "오늘 점검: F-001 passing 유지, F-003 failing 확인됨."
5. 내일도 같은 파일을 엽니다. 그게 살아 있는 뼈대의 시작입니다.

자가 점검 5문항

• ☐ 우리 프로젝트의 지금 활성 작업을 한 줄로 답할 수 있나요?
• ☐ AI가 자기 작업의 통과 여부를 스스로 확인할 수 있나요?
• ☐ state 칸이 거짓말하고 있을 가능성을 정기적으로 점검하나요?
• ☐ verification 칸이 비어 있는 항목이 있나요?
• ☐ feature_list.json이 사람과 AI 둘 다 매일 읽고 갱신하나요?

세 개 이상 아니오라면, 오늘 5분 액션이 정확히 당신을 위한 과제입니다.

마무리, 그리고 다음 챕터

다시 한번.

feature_list.json 한 장이, 흩어진 작업을 살아 있는 뼈대로 묶습니다. 메모가 아니라 시스템입니다.

뼈대가 섰다면, 이제 그 뼈대 위에 증거를 올릴 차례입니다. 챕터 9 — "됐어요"를 믿지 마라, 증거를 요구하라. AI의 "완료했습니다"가 정말인지 어떻게 확인할지, 검증 루틴을 같이 만들어 보겠습니다.

참고

• 원본 강의: walkinglabs.github.io/learn-harness-engineering/ko/ 강의 08
• Eugene Yan, "How to Work and Compound with AI", eugeneyan.com/writing/working-with-ai/