에이전트가 실행할 수 있는 명세는 무엇이 다른가

이 사이트를 만들며 명세를 세 번 다시 썼다. 세 번 다 같은 자리에서 틀렸는데, 문서가 부실해서가 아니었다. 오히려 잘 읽히는 문서였다 — 배경이 있고 의도가 적혀 있고 왜 그렇게 정했는지가 설명돼 있었다. 그런데 그 문서를 들고 작업을 시작하면 매번 다른 결과가 나왔다.

빠진 것은 설명이 아니라 판정이었다. 사람은 명세를 읽다가 애매한 자리를 만나면 자기 경험으로 메우거나 물어본다. 에이전트는 둘 다 하지 않는다. 그 자리에 그럴듯한 값을 만들어 넣고 계속 간다. 지어낸 티도 안 난다 — 문장이 매끄럽기 때문이다.

완료 조건은 문장이 아니라 명령이다

가장 먼저 고친 것이 이 자리다. “사이트가 잘 보이면 된다”는 명세가 아니다. 무엇이 잘 보이는 것인지 판정할 방법이 없어서, 결국 매번 사람이 화면을 열어보고 그때그때 정하게 된다.

이 레포의 지침 파일에는 완료 판정이 돌려볼 수 있는 명령으로 적혀 있다. npm run build 가 통과하고, 화면은 로컬 dev 서버에서 확인한다. 이렇게 적어두면 에이전트가 스스로 한 번 더 확인하고 끝낸다 — 사람에게 “다 됐습니다”를 말하기 전에 통과 여부를 자기가 안다.

여기서 한 가지를 배웠다. 빌드가 통과하는 것과 화면이 맞는 것은 다르다. 지난 세션에 빌드는 멀쩡히 통과했는데 화면에서 두 번 버그가 드러났다. 그래서 완료 조건을 명령 하나로 두지 않고 두 줄로 쪼갰다 — 빌드가 통과하는가, 그리고 실제 화면이 의도대로 보이는가. 판정 방법이 하나뿐인 명세는 그 하나가 놓치는 것을 통째로 놓친다.

강제할 것과 표시할 것을 가른다

명세를 코드로 내릴 수 있게 되면 다음 유혹이 온다. 원칙을 전부 스키마로 강제하는 것이다.

이 프로젝트의 원래 원칙은 “직접 해본 것만 쓴다”였다. 그럴듯했고, 그래서 스키마에도 넣었다 — 재료가 없는 트랙에서는 절차를 다루는 글을 못 쓰게 트랙별로 허용 타입을 제한했다. 지식·업무 시스템 트랙에는 기록 타입만 열어뒀다.

문제는 그 트랙이 이 프로젝트에서 가장 알고 싶은 주제였다는 것이다. 아직 제대로 운영해본 적이 없으니 경험이 없고, 경험이 없으니 규칙에 걸려 아무것도 못 쓴다. 규칙을 지키는 유일한 방법이 그 주제를 안 다루는 것이 됐다. 규칙이 막으려던 건 거짓말이었는데, 실제로 막은 건 학습이었다.

풀어낸 방법은 규칙을 없애는 게 아니라 자리를 옮기는 것이었다. 지켜야 할 선은 “해보지 않은 것을 해본 것처럼 쓰지 않는다” 하나로 좁히고, 그건 막는 대신 basis 필드로 드러내기로 했다. 직접 해봤는지, 조사해서 정리한 것인지, 섞였는지가 글마다 표시된다. 조사만으로 쓴 글도 쓸 수 있고, 독자는 그게 조사라는 걸 알고 읽는다.

자리	고르는 조건	이 레포의 예
검증으로 내린다	어기는 경우가 전부 실수일 때	분류 필드에 기본값을 두지 않아, 빠뜨리면 빌드가 실패한다. 출처를 적었는데 확인일이 없어도 실패한다
표시로 남긴다	어겨도 결과물은 나오고 신뢰 수준만 달라질 때	basis — 근거가 경험인지 조사인지 글마다 밝힌다
비워둔다	사람만 아는 값일 때	기존 글의 근거 표시. 에이전트가 추측해 채우면 그 자체가 규칙 위반이 된다

첫 줄과 둘째 줄을 가르는 기준이 실제로 값을 한다. 출처를 적어놓고 확인일을 안 적는 건 실수 말고 다른 이유가 없다 — 그래서 빌드가 막는다. 반대로 근거가 경험인지 조사인지는 어느 쪽이든 정당한 글이라서, 막을 게 아니라 밝힐 일이다.

비워둔 자리는 결함이 아니다

명세를 쓰다 보면 빈칸이 부끄러워진다. 다 정해놓은 문서가 완성도 높아 보이기 때문이다. 그런데 에이전트를 붙이면 계산이 뒤집힌다. 비어 있는 자리보다 잘못 채워진 자리가 훨씬 비싸다. 비어 있으면 물어보게 되고, 잘못 채워져 있으면 그대로 실행된다.

이 레포에 그 자리가 하나 있었다. 초기에 쓴 글 열여섯 편에 근거 표시가 없었는데, 어느 글이 직접 해본 것이고 어느 글이 조사가 섞인 것인지는 쓴 사람만 안다. 글을 읽고 추론하면 그럴듯한 값이 나오기는 한다 — 도구를 다룬 글이니 직접 써봤겠지, 하는 식으로. 그리고 그렇게 채운 값은 정확히 이 프로젝트가 하지 않기로 한 것이 된다.

그래서 명세에 “이건 저자에게 묻는다”를 적어두고 필드는 선택값으로 열어뒀다. 값이 없으면 화면에 근거 줄이 아예 안 뜨도록 해서, 빈칸이 거짓말로 보이지 않게 했다. 열여섯 편은 결국 저자에게 물어서 채웠다. 물어보는 데 든 시간은 몇 분이었고, 추측으로 채웠다면 되돌리는 데 훨씬 오래 걸렸을 것이다.

하지 말 것이 절반이다

명세는 만들 것을 적는 문서라고 생각하기 쉽다. 에이전트에게 넘기면 반대쪽이 더 중요해진다. 무엇을 만들지는 요청 문장에 이미 있지만, 어디서 멈춰야 하는지는 아무 데도 안 적혀 있기 때문이다.

이 프로젝트의 방향 문서에는 단계별로 무엇을 켤지와 함께, 그 단계에 도달하기 전에는 시작하지 않을 것이 따로 적혀 있다. 계정, 원격 실습 환경, 생성형 미디어 — 전부 한 번 켜면 끄기 어렵고 비용이 계속 나가는 것들이다. 조건을 통과하기 전에는 손대지 않는다고 문서에 박아뒀다.

이건 에이전트를 못 믿어서가 아니다. 요청을 잘 수행하려는 쪽으로 기울면 “이왕이면 이것도 해두면 좋겠다”가 자연스럽게 따라오는데, 되돌리기 어려운 일에서는 그 친절이 비싸다. 승인 게이트를 어디에 둘지 정하는 것과 같은 판단이고, 명세에서는 그게 목록 한 절로 나타난다.

이 문서를 덮어도 되는 시점

지금 쓰고 있는 명세에서 세 가지를 확인할 수 있으면 된다. 완료 조건이 돌려볼 수 있는 명령으로 적혀 있는가. 하지 말 것이 따로 한 절 있는가. 사람만 아는 값이 채워진 채가 아니라 비워진 채 표시돼 있는가.

셋 다 없어도 문서는 잘 읽힐 수 있다. 다만 그 문서로는 같은 결과가 두 번 나오지 않는다.

변경 로그

• 2026-07-27초안 작성. 이 레포에서 명세를 세 번 고쳐 쓰며 나온 판단 — 완료 조건을 명령으로, 규칙을 강제·표시·빈칸 세 자리로, 하지 말 것을 따로. 트랙 ③ 의 첫 글이라 예시는 전부 이 레포에서 가져왔다 (성숙도: 탐색 중)
• 예정같은 명세를 다른 에이전트에게 넘겨 같은 결과가 나오는지 확인 · 명세를 쪼개는 단위(한 세션에서 끝나는 크기)에 대한 기준 보강