slipway 소개 — 하네스 코딩으로 세운 스타터 키트이자 골든 패스

케네스랩은 요즘 AI 코딩 에이전트와 함께 코드를 씁니다. 사람은 무엇을 만들지 정하고, 에이전트가 쓴 결과를 검토하고, 배포를 결정합니다. 에이전트에게 일을 맡겨 보면 금방 알게 되는 사실이 있습니다. 같은 모델이라도 저장소에 따라 결과가 크게 다르다는 것입니다. 규칙이 정리된 저장소에서는 기존 방식을 잘 따르지만, 그렇지 않은 저장소에서는 매번 새로운 방식으로 서버를 부르고, 열지 말아야 할 설정 파일을 열어 보고, 확인하지 않은 채 "됐습니다"라고 보고하기도 합니다.

차이는 모델이 아니라 모델 바깥에 있었습니다. 저장소에 어떤 문서가 있고, 어떤 검사가 돌고, 무엇이 막혀 있는가. 이번 글에서는 이 "모델 바깥"을 하나의 키트로 만든 slipway를 소개합니다. slipway는 PHP·JavaScript·HTML 웹 프로젝트를 위한 공용 규칙 문서, 배포 체계, 골조 코드를 한 묶음으로 담은 키트이며, 지금 케네스랩이 진행하는 여러 프로젝트가 이 위에서 만들어지고 있습니다.

이름은 배를 물에 내리는 경사로인 진수대(slipway)에서 왔습니다. 진수대 위의 배가 레일을 따라 바다로 미끄러져 내려가듯, 코드가 개발(dev) → 검증(stage) → 운영(live)으로 정해진 길을 따라 내려가기를 바라는 마음을 담았습니다.

하네스 코딩이란

하네스(harness)는 원래 말에 채우는 마구, 또는 시험 장비에 부품을 물려 두는 틀을 뜻합니다. AI 코딩에서 말하는 하네스는 모델을 뺀 에이전트의 나머지 전부입니다. 흔히 "에이전트 = 모델 + 하네스"라고 정리합니다. 작업 지침 문서, 쓸 수 있는 도구와 권한, 코드를 고친 직후 돌아가는 검사, 커밋을 막는 훅, 테스트, 프로젝트 템플릿, 배포 게이트가 모두 하네스에 속합니다. 이 하네스를 설계하고 다듬는 일을 하네스 코딩, 또는 하네스 엔지니어링이라고 부릅니다.

이 말이 널리 퍼진 계기는 OpenAI가 2026년 초에 공개한 경험담입니다. 사람이 직접 쓴 소스 코드 없이 Codex 에이전트만으로 약 100만 줄 규모의 제품을 만들었는데, 그동안 엔지니어가 한 일은 코드를 쓰는 것이 아니라 에이전트가 일할 환경을 만들고, 의도를 문서로 남기고, 결과를 되먹이는 고리를 짜는 것이었다는 내용이었습니다. 이후 Thoughtworks의 비르기타 뵈켈러(Birgitta Böckeler)가 마틴 파울러(Martin Fowler)의 사이트에서 이 개념을 정리하면서 하나의 분야로 자리 잡았습니다.

하네스의 장치는 크게 두 갈래로 나눌 수 있습니다.

• 미리 이끄는 장치(가이드) — 에이전트가 움직이기 전에 방향을 잡아 줍니다. 작업 지침, 규칙 문서, 템플릿, 쓸 수 있는 도구의 범위가 여기에 속합니다.
• 결과를 재는 장치(센서) — 에이전트가 움직인 뒤 결과를 확인해 스스로 고치게 합니다. 검사기, 테스트, 훅, 배포 전 확인이 여기에 속합니다.

하네스 코딩의 핵심은 관점의 전환입니다. 에이전트가 실수하면 프롬프트를 고쳐 다시 부탁하는 대신, 그 실수가 다시 일어날 수 없는 환경을 만듭니다. 실수 하나가 대화 한 번으로 끝나지 않고, 규칙 한 줄과 검사 하나로 저장소에 남습니다. 그래서 하네스는 시간이 갈수록 두꺼워지고, 같은 모델로도 결과가 점점 안정됩니다.

스펙 주도 개발이란

스펙 주도 개발(Spec-Driven Development, SDD)은 코드보다 명세를 먼저 쓰고, 그 명세를 기준으로 AI가 계획과 구현을 뽑게 하는 방식입니다. "로그인 기능 만들어 줘"라고 바로 시키는 대신, 무엇을 왜 만드는지, 어떤 경우에 어떻게 동작해야 하는지를 문서로 먼저 정하고 그 문서를 에이전트에게 줍니다.

대표적인 도구로는 명세(Spec) → 계획(Plan) → 작업(Tasks) → 구현(Implement) 순서로 일을 나누는 GitHub의 Spec Kit, 요구사항·설계·작업 목록 문서를 먼저 만들게 하는 AWS의 Kiro, 명세 자체를 1차 산출물로 삼는 Tessl이 있습니다. 앞서 말한 뵈켈러는 스펙 주도 개발을 세 수준으로 나눴습니다.

• 명세 우선(spec-first) — 구현 전에 명세를 쓰고 그 작업에 씁니다. 작업이 끝난 뒤에도 명세를 관리할지는 정하지 않습니다.
• 명세 고정(spec-anchored) — 기능을 고칠 때마다 명세도 함께 고쳐, 명세가 계속 살아 있게 합니다.
• 명세가 곧 소스(spec-as-source) — 사람은 명세만 고치고, 코드는 명세에서 만들어지는 생성물로 봅니다.

스펙 주도 개발은 AI가 엉뚱한 것을 만드는 문제를 잘 줄여 줍니다. 다만 시간이 지나며 명세를 어떻게 관리할지가 흐릿하게 남는 경우가 많고, 문서가 과해지면 애자일이 벗어나려 했던 무거운 절차가 돌아온다는 지적도 있습니다.

둘은 무엇이 다른가

두 방식 모두 "AI에게 일을 잘 시키는 법"이라 비슷해 보이지만, 겨누는 곳이 다릅니다. 스펙 주도 개발은 이번에 무엇을 만들 것인가를 다루고, 하네스 코딩은 어떤 작업이든 어떻게 일하게 할 것인가를 다룹니다.

그래서 둘은 경쟁 관계가 아니라 서로를 채웁니다. 명세만 있고 하네스가 없으면, 에이전트는 명세를 만족하는 기능을 만들되 프로젝트마다 다른 방식으로 서버를 부르고 보안 규칙을 빠뜨립니다. 하네스만 있고 명세가 없으면, 규칙은 잘 지켰지만 아무도 원하지 않은 기능이 깔끔하게 완성됩니다.

slipway는 하네스 쪽에 무게를 둔 키트이지만, 명세를 쓰는 자리도 함께 정해 둡니다. 여러 프로젝트가 함께 쓰는 규칙은 docs/common/에, 그 프로젝트만의 명세와 사정은 docs/ 최상위에 둡니다. 화면이나 기능의 명세를 쓸 때는 정해진 틀을 따릅니다.

• 시나리오와 경계 상황을 표로 적습니다. 빈 목록, 권한 없음, 로그인 만료, 파일 없음 같은 경우를 빠뜨리지 않습니다.
• 검증 방법을 적습니다. "어떤 명령을 돌리면 무엇이 나와야 한다"처럼 확인할 수 있게 씁니다.
• 범위 밖을 최소 한 줄 적습니다. 비워 두면 다음 사람이 그 빈자리를 짐작으로 채우기 때문입니다.
• 정하지 못한 것은 [미정: 질문]으로 표시하되 한 문서에 세 개까지만 둡니다. 그보다 많으면 아직 문서를 쓸 때가 아니라 물어볼 때입니다.

즉 slipway 안에서 명세는 "이번 배의 설계도"이고, 하네스는 그 설계도를 받아 배를 짓는 조선소입니다.

slipway가 지향하는 것

slipway를 만들며 지켜 온 목표는 여섯 가지입니다.

1. 첫날부터 서 있는 프로젝트

새 프로젝트를 시작할 때 문서 구조, 배포, 라우터, 화면을 그리는 렌더러, 로그인과 권한까지 이미 서 있는 상태에서 출발합니다. 첫 기능을 만들기 전에 기반 공사로 몇 주를 쓰지 않고, 에이전트도 첫날부터 "이 저장소에서는 이렇게 한다"는 본보기를 보고 일합니다.

2. 좋아진 것은 모든 프로젝트로 다시 흐른다

보통의 템플릿은 복사하는 순간 원본과 갈라집니다. 템플릿이 나중에 좋아져도 이미 만든 프로젝트에는 전해지지 않습니다. slipway는 프로젝트에 깔리는 파일을 두 종류로 나눕니다.

• 공용본 — 공용 규칙 문서, 배포 엔진, 검사기, 훅. 프로젝트에서 고치지 않고, 키트가 갱신되면 그대로 덮어씁니다.
• 씨앗 — 라이브러리, 관리 화면 골조, 설정 예시. 처음에 깔린 뒤로는 프로젝트가 가져가 고칩니다. 키트에서 씨앗이 좋아지면 3-way 병합으로 가져옵니다. 프로젝트가 고친 부분은 남고, 겹치는 곳만 충돌로 표시됩니다.

병합의 기준은 프로젝트에 남겨 둔 키트 커밋입니다. 한 프로젝트에서 부딪혀 고친 문제가 키트로 올라가고, sync 한 번으로 다른 모든 프로젝트에 내려갑니다.

3. 결정적인 일은 스크립트가, 판단은 AI가

slipway는 세 층으로 되어 있습니다. 파일 복사, 값 치환, 병합처럼 결과가 늘 같아야 하는 일은 bin/slipway 스크립트가 합니다(init, sync, check). AI는 사람에게 필요한 값을 묻고, 스크립트를 부르고, 결과를 설명하는 일만 합니다. 스킬과 스크립트, 템플릿은 Claude Code 플러그인 하나로 묶여 설치됩니다. 덕분에 slipway는 AI 없이도 돌고, AI가 있을 때는 대화로 쓸 수 있습니다.

4. 문서로 쓴 규칙은 기계가 지킨다

규칙은 사람이 읽을 수 있게 산문으로 씁니다. 하지만 문서에만 있는 규칙은 잊히기 마련입니다. 그래서 기계가 판정할 수 있는 규칙은 검사기(check-rules.php)가 지킵니다. 클래스 파일 이름과 위치, 상태를 바꾸는 요청은 POST로만 받는지, 화면 스크립트가 서버를 직접 부르지 않고 정해진 통로를 쓰는지, 보안 정책(CSP)에 어긋나는 인라인 스크립트가 없는지 같은 것들입니다.

"오탐을 내지 않는 것이 이 검사의 생명이다. 한 번 빨간불이 잘못 켜지면 사람이 훅을 꺼 버리고, 꺼진 게이트는 없는 것보다 나쁘다." — 검사기 첫머리의 주석

집행은 시점이 다른 세 겹으로 겹칩니다.

• 작업 중 — Claude Code의 권한 설정과 훅이 비밀 설정 파일 읽기, 공용본 편집, 시키지 않은 커밋을 도구를 부르는 순간 막습니다.
• 고친 직후 — 파일을 고칠 때마다 검사기가 돌아 위반을 바로 알립니다. 응답을 마치기 전에도 한 번 더 확인합니다.
• 커밋할 때 — git 훅이 비밀 값, DB 덤프, 토큰, 규칙 위반이 든 커밋을 막습니다.

slipway 문서는 앞의 두 겹을 "담이 아니라 과속방지턱"이라고 부릅니다. 문자열을 보고 판정하므로 빠져나갈 길이 있다는 것을 인정하고, 진짜 담은 마지막 git 훅에 둡니다. 완벽한 척하는 장치보다 한계를 아는 장치가 더 오래 쓰입니다.

5. 운전대는 사람이 잡는다

에이전트 도구는 기본적으로 작업 전에 브랜치를 만들고, 끝나면 커밋하려고 합니다. slipway 프로젝트에서는 git은 사람이 몹니다. 이력은 사람이 읽는 기록이기 때문입니다. 에이전트는 바꾼 것을 작업 트리에 두고 무엇을 왜 바꿨는지 보고합니다. 사람이 커밋을 시키면 그때 명령 앞에 허용 표시를 붙여 통과시키는데, 이 표시는 화면에 그대로 보이므로 사람은 자기가 시킨 것이 맞는지 알 수 있습니다.

배포도 같습니다. 검증 서버(stage)가 있는 프로젝트는 같은 커밋을 stage에 먼저 올리지 않으면 운영(live) 배포가 막힙니다. 기획서처럼 외부에 있는 자료도 사람이 지정한 폴더만 읽을 수 있고, 에이전트가 그 범위를 스스로 넓히지 못하게 되어 있습니다.

6. "됐다"에는 증거가 있어야 한다

에이전트가 가장 자주 하는 실수는 확인하지 않고 끝났다고 말하는 것입니다. slipway는 "됐다"고 말하기 전에 거칠 다섯 단계를 정해 두었습니다. 무엇이 증명하는지 정하고, 지금 새로 돌리고, 출력을 끝까지 읽고, 주장과 대조한 뒤에 말합니다. "화면이 뜬다"의 증거는 코드가 그럴듯해 보이는 것이 아니라 실제 주소를 열어 받은 응답이고, "버그를 고쳤다"의 증거는 원래 증상을 재현하던 절차가 이제 통과하는 것입니다.

"'될 겁니다', '아마', '~인 것 같습니다'가 보고에 나오면 검증을 하지 않았다는 신호입니다." — slipway 작업 방식 문서

스타터 키트로서의 slipway

slipway의 첫 번째 얼굴은 스타터 키트입니다. 기준 환경은 PHP 8.5, MariaDB, nginx입니다. 명령 한 줄이면 프로젝트의 골조가 섭니다. 값을 주지 않으면 터미널에서 묻고, 이미 있는 파일은 덮어쓰지 않습니다.

slipway init ~/work/myproj --set PROJECT_NAME='내 프로젝트' --set DOMAIN=myproj.kr

이 명령이 깔아 주는 것은 다음과 같습니다.

myproj/
├── CLAUDE.md          에이전트 작업 지침 + 문서 색인 (항상 읽는 규칙은 300줄 안에)
├── .claude/           에이전트 권한 거부 목록과 훅 등록
├── docs/
│   └── common/        공용 규칙 18종 — 기본 → 설계 → 서버 코드 → 화면 코드 → 검토 → 배포 순
├── libs/              설정·DB·요청·라우터·렌더러·폼 토큰·인증·가드·S3·메일·엑셀
├── admin/             관리 화면 골조, 공통 CSS·JS, 웹폰트
├── client/            사용자 화면 골조
├── config/            개발·검증·운영 × 일반·민감 설정 분리
├── deploy/            배포 엔진 — 되돌리기, 배포 기록, 헬스체크, 배포 잠금, 마이그레이션 큐
├── githooks/          비밀 값·DB 덤프·토큰·규칙 위반 차단
└── scripts/           검증기, 규칙 검사기, 에이전트 훅

그래서 첫 커밋부터 로그인, 권한 가드, 배포 체계, 규칙 검사가 있습니다. 주소 규칙은 (도메인)/(모듈)/(기능) 하나이고, 라우터는 modules/(모듈)/(기능).php를 바로 찾습니다. 클래스는 파일 하나에 하나, 파일 이름이 곧 클래스 이름입니다. 단순한 규칙은 사람에게도 에이전트에게도 같은 장점이 있습니다. 어디에 무엇이 있을지 짐작이 맞습니다.

여기에 앞서 말한 sync가 더해집니다. 프로젝트에 남긴 키트 버전을 기준으로 공용본은 덮어쓰고 씨앗은 병합하므로, slipway로 세운 프로젝트는 한 번 복사하고 끝나는 보일러플레이트가 아니라 계속 같이 자라는 골조가 됩니다.

골든 패스로서의 slipway

골든 패스(golden path)는 Spotify가 널리 알린 말로, 넷플릭스는 비슷한 개념을 "포장된 길(paved road)"이라고 부릅니다. 조직이 권하고 지원하는, 가장 쉬운 표준 경로를 뜻합니다. 다른 길을 막지는 않지만, 이 길로 가면 도구와 문서와 검사가 다 갖춰져 있어서 대부분의 일은 이 길 위에서 끝납니다.

slipway의 두 번째 얼굴이 이 골든 패스입니다. 자주 마주치는 일마다 "이 저장소에서는 이렇게 한다"는 길이 하나씩 정해져 있습니다.

골든 패스가 AI 시대에 더 중요한 이유가 있습니다. 사람은 팀의 관습을 눈치로 배우지만, 에이전트는 길이 여러 개면 매번 다른 길을 고릅니다. 같은 일을 하는 코드가 세 가지 방식으로 생기고, 리뷰하는 사람은 매번 새로운 방식을 읽어야 합니다. 길이 하나이고 그 길을 벗어나면 검사기가 알려 주면, 에이전트의 결과물은 자연스럽게 한 모양으로 모입니다.

물론 길을 벗어나야 할 때도 있습니다. slipway는 그것을 막지 않는 대신 기록하게 합니다. 공용 규약을 어기는 자리는 문서의 예외 표에 "어긴 규약, 왜 필요한가, 더 단순한 대안을 고르지 않은 이유, 언제 끝나는가"를 적습니다.

"한 칸이라도 비면 예외가 아니라 습관입니다." — slipway 문서 쓰는 틀

그리고 길을 고치는 곳은 한 군데입니다. 공용본을 프로젝트에서 직접 고치면 다음 sync에서 사라집니다. 규칙이나 배포 엔진을 바꾸려면 키트에서 고치고 버전을 올린 뒤 각 프로젝트에서 sync합니다. 그래야 골든 패스가 프로젝트마다 조금씩 다른 여러 갈래의 길로 갈라지지 않습니다.

지금까지의 slipway

slipway 1.0.0은 2026년 9월 4일에 나왔습니다. 처음에는 공용 문서와 배포 스크립트 정도였는데, 프로젝트에서 부딪힌 문제를 하나씩 키트로 올리면서 7주 동안 45번의 커밋을 거쳐 10월 21일 현재 4.8.3이 되었습니다. 그사이 배포 엔진에 되돌리기와 헬스체크가, 규칙 검사기와 에이전트 훅이, 화면 설계 원칙과 파일 업로드 규약이 더해졌습니다. 지금은 케네스랩이 진행하는 여덟 개 프로젝트가 slipway 위에서 만들어지고 있고, 한 프로젝트에서 얻은 교훈이 sync를 타고 나머지 일곱 프로젝트로 내려갑니다.

맺으며

AI 그리고 개발자의 미래에서 AI가 개발을 바라보는 관점 자체를 바꾸고 있다고 이야기했습니다. slipway를 만들며 느낀 것은, 그 변화의 한가운데에 일하는 방식을 코드로 적는 일이 있다는 점입니다. 좋은 모델은 누구나 쓸 수 있습니다. 차이를 만드는 것은 그 모델이 어떤 문서를 읽고, 어떤 길을 걷고, 어떤 검사를 통과하는가입니다.

스펙 주도 개발이 "이번에 무엇을 만들까"를 분명히 해 준다면, 하네스 코딩은 "어떤 일이든 이 수준으로 한다"를 보장합니다. slipway는 그 하네스를 케네스랩의 모든 프로젝트가 함께 쓰는 스타터 키트이자 골든 패스로 만든 결과입니다. 진수대 위의 배가 레일을 따라 바다로 나가듯, 우리 코드도 정해진 길을 따라 안전하게 운영 환경으로 내려가기를 바랍니다.