이 문서는 structure-first 스킬이 만들어지게 된 배경과,
개발 과정에서 겪은 시행착오와, 스킬이라는 형식에 도달하기까지의 생각을 정리한 기록입니다.
저는 여러 도메인과 서비스를 혼자서 개발 및 운영해본 경험을 가지고, 팀 단위로 기존 프로젝트를 개선하며 개발팀 전체를 책임지는 역할까지 다양한 경험을 해봤습니다. 코드를 작성하며 효과적인 방법들을 고민했고 나름의 방식을 만들기 시작했습니다.
동료와 앉아 페어 프로그래밍을 하거나 누가 만들었을지 모를 레거시 코드를 고치면서 코드를 정리하는 요령이 쌓였습니다. 코드 정리의 핵심은 흐름이 읽히고, 적절한 경계를 탐색하며, 단단한 조각들을 조합해 비즈니스 목표를 빠른 시간 안에 달성하는 것이었습니다. 코드가 읽기 좋아지자 적은 인원으로도 많은 기능을 감당할만 했습니다.
제가 주로 썼던 것은 Python이었기에 더욱 빠른 대응이 가능했겠지만, Python으로 된 코드라도 여러 사람의 손을 타면 점점 복잡해지고 개성이 드러나 읽기 어렵긴 마찬가지였습니다. 그래서 다시 제가 감각을 코드에 녹이는 시간이 필요했습니다.
주니어 개발자의 역량을 향상시키는 일은 늘 도전이었습니다.
제가 쌓아온 감각은 짧은 시간 안에 밀도 있게 전달할 만한 형태가 아니었고, 저 역시 그것을 잘 정리해두지 못한 상태였습니다. 대부분의 회사에서는 이런 시도를 충분히 이어갈 시간도 여유도 부족했습니다.
지속적인 관심을 가지고 주니어 개발자와 1:1 코칭으로 밀도 있게 업무를 하면 굉장히 효과적이였지만, 그럴 기회가 주어지는 것은 상황이 맞아떨어지는 운이 필요했습니다.
AI 에이전트로 개발하는 흐름이 대세가 되면서, 생산성 향상과 함께 AI 코드의 한계도 분명히 드러나기 시작했습니다.
특히 복잡한 상태를 다루는 코드일수록 그 취약함이 두드러졌습니다.
며칠에 걸쳐 꽤 복잡한 프론트엔드 코드를 AI와 함께 작성하면서, 결과적으로는 목적을 달성할 수 있었지만 그 과정에서 프롬프트 시행착오는 계속 쌓여갔습니다.
처음에는 AI와 페어 프로그래밍을 하듯 제가 추구하는 코드 방향을 계속 지시하다가, 어느 순간부터는 그런 시도를 포기하고 테스트만 통과한다면 적당히 수용하는 타협을 하게 되기도 했습니다.
주 관심사 중 하나는 주니어 개발자들의 성장을 AI로 어떻게 도울 수 있을지에 대한 고민이었습니다.
그 과정에서, agentskills.io로 제가 평소에 작성하던 코드 방식을 만들어볼 수 있지 않을까 하는 생각이 들었습니다.
ChatGPT 초기부터 지금까지 GPT를 활용해 코드를 리팩터링했던 경험들이 떠올랐고, GPT의 메모리 안에는 저의 코딩 방식이 남아 있었습니다. 이를 GPT와 함께 다시 정리하니 실제로 제품 코드에 적용해왔던 핵심적인 판단 기준들이 조금씩 드러났습니다. 다만 이것을 AGENTS.md에 적어둔다고 AI가 그대로 동작하지 않을거라는건 이미 경험을 통해 알 수 있었습니다.
그래서 저는 이 판단 흐름을, 자연스럽게 따르기만 해도 핵심 가치가 지켜지는 지침의 형태로 만들어보았습니다.
그리고 제가 진행하던 프로젝트에 직접 적용해보았습니다.
$structure-first 를 참고해서 지금 만들던 지도 기능을 처음부터 다시 고민해봐
다른 주니어 개발자가 만든 프로젝트에도 적용해보았습니다.
$structure-first 관점으로 프로젝트 구조를 다시 제안해봐
결과는 꽤 잘 작동했습니다.
마치 제가 신경 써서 짠 것과 비슷한 느낌이 나는 코드들이 만들어졌습니다. 메인 흐름을 담당하는 부분은 제가 읽기에도 좋았으며, 작은 함수들은 읽을만한 테스트 코드로 동작을 보장할 수 있었습니다. 또한 복잡한 상황도 AI가 쉽게 대응하는 것을 확인했습니다.
structure-first가 사람과 AI 모두 읽기 쉽고 버그도 덜 발생하는 코드를 작성할 수 있을지를 여러분과 확인해보고자 이 스킬을 공개합니다.
이 스킬의 내용은 제품 코드를 다루며 겪어온 경험 속에서 자연스럽게 반복되던 판단들을 엮은 것입니다. 그래서 새로운 원칙이 아니라 이미 익숙한 개념들이 녹아있습니다.
코드의 경계를 나누는 방식에서 클린 아키텍처나 레이어드 아키텍처를 떠올릴 수 있습니다. 정리 순서나 리듬에서는 Kent Beck의 tidy-first를 읽으며, 제가 하던 방식과 닮아 있다고 느꼈던 지점들도 있습니다. 테스트 역시 TDD와 비슷해 보이지만, 구현을 이끄는 수단이라기보다 계약을 확인하는 장치에 가깝습니다.
다만 이런 원칙들을 그대로 적용하는 일은 쉽지 않았습니다. 어디까지가 과한지, 어디서 멈춰야 하는지는 상황마다 달랐고, 그 기준을 문서로 고정하는 것도 현실적으로 어려웠습니다. 그럼에도 여러 프로젝트를 거치며 반복되던 판단의 흐름들이 있었고, 이를 최대한 실용적인 형태로 묶어본 결과가 이 스킬입니다.