하네스 엔지니어링 튜토리얼 #2 — 적어두지 않은 규칙은, 없는 규칙이에요

지난 편에서 네 개의 기둥을 말씀드렸어요. 알린다, 제한한다, 검증한다, 교정한다. 오늘은 첫 번째, 알리는 일이에요.

가장 지루해 보이는 기둥인데 효과는 제일 큽니다. 저는 이 순서를 몰라서 한참을 돌아갔어요.

세 번 말했는데 네 번째에도 똑같았어요

말로 하는 규칙은 안 지켜져요.

정확히 말하면, 그 대화에서는 지켜져요. 창을 닫기 전까지는요. 그런데 다음 날 다시 켜면 그 규칙은 없던 게 됩니다. 도구는 어제 우리가 무슨 약속을 했는지 기억하지 못하니까요.

저는 이걸 인정하는 데 시간이 좀 걸렸어요. 같은 주의를 세 번쯤 주고 나면 사람은 화가 나거든요. 몇 번을 말해야 아느냐고요. 그런데 도구 입장에서는 처음 듣는 말이에요. 매번요.

그래서 어느 순간부터는 화를 내는 대신 적기 시작했어요.

적어두면 규칙이 되고, 안 적으면 취향이 돼요

여기서 제가 배운 문장이 하나 있어요. 좀 극단적으로 들리는데, 겪어보니 정확했어요.

선언 파일에 없는 규칙은, 사실상 존재하지 않는다.

선언 파일이라는 말이 딱딱하죠. 실체는 그냥 도구가 시작할 때 자동으로 읽는 문서예요. 클로드 코드라면 프로젝트 폴더에 CLAUDE.md라는 이름으로 두면 되고, 다른 도구를 쓰신다면 AGENTS.md처럼 그 도구가 정해둔 이름이 있어요. 이름만 맞춰 만들어두면 매번 알아서 읽힙니다. 대단한 설정이 아니라 그냥 마크다운 문서 한 장이에요.

머릿속에 있는 규칙은 규칙이 아니에요. 그냥 내 취향이에요. 도구가 그걸 지킬 확률은 그날그날 다릅니다. 운이 좋으면 지켜지고, 나쁘면 안 지켜져요. 그리고 우리는 그 운을 실력으로 착각하곤 해요. 잘 될 때는 프롬프트를 잘 썼다고 믿고, 안 될 때는 모델 탓을 하죠.

파일에 적는 순간 그건 규칙이 됩니다. 매번 읽히고, 매번 적용되고, 무엇보다 틀렸을 때 어디를 고쳐야 하는지가 분명해져요. 이게 생각보다 큰 차이예요. 머릿속 규칙은 고칠 자리가 없거든요.

무엇을 적냐면

거창하지 않아요. 저는 이 네 가지를 적습니다.

배경. 나는 무슨 일을 하는 사람이고, 이 작업은 누구를 위한 것인가. 도구는 이걸 모르면 일반론을 말해요. 우리가 원하는 건 내 상황에 맞는 답인데요.

결과물의 모양. 어떤 형식으로, 어느 정도 길이로, 어떤 톤으로. 이게 없으면 매번 다른 모양이 나오고, 우리는 매번 다시 시킵니다. "표로 정리해줘", "존댓말로 써줘" 같은 걸 매번 말하고 있다면 그건 적어둘 때가 된 거예요.

하지 말 것. 이게 의외로 강력해요. 해야 할 일보다 하지 말아야 할 일이 결과를 더 많이 바꿔요. "확정 안 된 숫자는 쓰지 말 것" 한 줄이 열 문장의 지시보다 낫습니다. 저는 이 항목이 제일 길어요.

판단이 갈릴 때의 기준. 애매하면 물어볼 것인가, 알아서 할 것인가. 저는 되돌리기 어려운 일은 무조건 물어보라고 적어뒀어요. 파일을 지우거나, 바깥으로 뭔가 보내거나, 돈이 나가는 일 같은 것들이요.

처음엔 다섯 줄로 시작했어요. 지금은 좀 길어졌지만, 여전히 그냥 문서예요. 사람이 읽을 수 있는 문장으로 적힌 문서요. 문법도 없고 형식도 없어요. 후배에게 인수인계하듯 쓰면 됩니다.

진짜로 이렇게 생겼어요

말로만 하면 감이 안 오실 것 같아서, 처음 만들 때 이 정도면 충분하다 싶은 걸 적어볼게요. 마케팅 일을 하신다고 가정할게요.

내가 하는 일
소비재 브랜드의 마케팅 기획을 해요. 주간 리포트와 캠페인 기획서를 주로 씁니다. 읽는 사람은 팀 동료와 결정권자예요.
결과물의 모양
결론을 먼저 쓰고 근거는 뒤에. 표는 꼭 필요할 때만. 존댓말. 한 문단은 세 문장을 넘기지 않기.
하지 말 것
확정되지 않은 수치를 단정해서 쓰지 마세요. 출처가 없는 숫자는 아예 빼세요. 제가 쓰지 않은 표현을 지어내지 마세요.
애매할 때
자료가 부족하면 추측해서 채우지 말고 저에게 물어보세요. 파일을 지우거나 바깥으로 뭔가 보내는 일은 반드시 확인받고 하세요.

이게 전부예요. 열 줄 남짓이죠. 그런데 이 문서가 있는 것과 없는 것의 차이가, 제 경험으로는 모델 한 세대 차이보다 컸어요.

특히 세 번째 항목을 보세요. "출처 없는 숫자는 빼라"는 한 줄이, 그럴듯한 거짓말을 상당히 줄여줍니다. 도구는 빈칸을 싫어해서 뭐라도 채우려 하거든요. 그때 채우지 말고 비워두라고 미리 허락해주는 것이 이 한 줄의 역할이에요.

같은 규칙을 두 군데 적으면 생기는 일

여기서 함정이 하나 있어요. 저는 이걸로 몇 번 데였어요.

규칙을 적기 시작하면 자연스럽게 여기저기 적게 돼요. 지침 문서에도 적고, 실제로 돌아가는 자동화 쪽에도 적고, 다른 도구용으로 복사도 해두고요. 그때는 그게 꼼꼼한 일처럼 느껴져요.

그런데 규칙은 바뀝니다. 그리고 바뀔 때 한 군데만 고치게 돼요.

저한테 실제로 있었던 일이에요. 어떤 작업의 지시문이 문서 한 곳과 실행하는 쪽 한 곳, 이렇게 두 군데에 들어 있었어요. 문서를 고쳤는데 실행 쪽은 예전 것 그대로였어요. 그래서 저는 고친 규칙대로 돌아갈 거라고 믿고 있었고, 실제로는 옛날 규칙대로 돌고 있었어요.

이런 걸 드리프트(drift)라고 부르더군요. 두 사본이 조용히 어긋나는 현상이요.

조용히가 핵심이에요. 에러가 안 나요. 화면이 빨개지지도 않아요. 그냥 내가 아는 것과 실제가 달라질 뿐이에요. 그래서 발견이 늦습니다.

그래서 지금은 원칙이 하나예요. 규칙은 한 군데에만 둔다. 다른 데서는 그걸 가리키기만 하고요. 이걸 좀 있어 보이게 부르면 단일 정본(single source of truth)이라고 하는데, 실제로 하는 일은 단순해요. 규칙 본문은 한 파일에만 쓰고, 다른 파일에서는 "규칙은 저 문서를 봐라"라고 한 줄만 적어두는 거예요. 사본을 만들지 않는 겁니다.

사본은 반드시 어긋나거든요. 언제 어긋나느냐의 문제일 뿐이에요.

규칙이 늘어나면 생기는 다른 문제

한 가지 미리 말씀드릴 게 있어요. 지금 저는 적으라고 계속 말하고 있는데, 이게 무한정 좋은 건 아니에요.

문서가 길어지면 도구가 그걸 다 읽느라 힘들어져요. 도구가 한 번에 볼 수 있는 양에는 한계가 있는데(이걸 컨텍스트 윈도우라고 불러요, 작업 책상 넓이 같은 거예요), 지침이 그 책상의 절반을 차지하면 정작 일할 자리가 없어집니다.

그래서 저는 지침을 쪼갰어요. 항상 읽어야 하는 짧은 규칙과, 그 일을 할 때만 읽으면 되는 규칙으로요. 후자는 필요할 때만 불러옵니다. 실제로 하는 일은 긴 문서를 별도 파일로 빼고, 본 지침에는 "이 작업을 할 때는 저 문서를 읽어라" 한 줄만 남기는 거예요.

이 이야기는 여섯 번째 편에서 제대로 할게요. 지금은 이것만 기억하시면 돼요. 적는 건 좋다. 그런데 항상 읽히게 두는 건 다른 문제다.

그래서

도구에게 같은 말을 세 번째 하고 있다면, 그건 도구가 둔한 게 아니에요. 그 규칙이 아직 어디에도 적혀 있지 않은 거예요.

머릿속에 있는 건 규칙이 아닙니다. 파일에 있어야 규칙이에요.

---

📌 오늘 해볼 것

파일을 하나 만드세요. 클로드 코드를 쓰신다면 작업 폴더에 CLAUDE.md라는 이름으로요. 그리고 네 줄만 적어보세요.

내가 하는 일 / 결과물의 모양 / 하지 말 것 하나 / 애매할 때 물어볼지 말지.

다음에 뭔가를 시킬 때, 도구가 알아서 그 파일을 읽습니다. 그게 이번 편의 전부예요.

🗓 다음 편

두 번째 기둥, 제한하는 일이에요. 이 편은 제가 자동화를 잘못 걸어서 제 데이터를 지워버린 이야기로 시작합니다.

---