방법론을 강요하지 않고 공유하는 방법
2026.09.13 게시
이 시리즈는 작성 시점의 기록이다. 현재 기준은 Adaptive Agentic SDD 저장소에 정리해두었다.
![]()
개발 방법론을 실제 프로젝트에 적용하다 보니 조금 걸리는 부분이 생겼다.
한 파트에서 관리하는 프로젝트는 별문제가 없었다.
같이 일하는 사람들과 협의해서 같은 방법론을 적용하면 됐으니까.
그런데 여러 파트가 함께 개발하는 프로젝트는 달랐다.
내가 쓰려고 프로젝트에 방법론을 넣었는데, 그게 다른 파트에도 같이 적용된다면?
다른 파트는 자기들 방식이 있을 텐데 굳이 내가 선택한 방법론을 따라야 할 이유가 없다.
생각해보면 같은 파트도 마찬가지다.
내가 이 방법론이 좋다고 생각해도 옆 사람은 안 쓰고 싶을 수 있다. 다른 방식이 더 편할 수도 있고, 맡은 업무에 더 잘 맞는 방법론이 따로 있을 수도 있다.
같은 프로젝트를 개발한다고 해서 작업하는 방식까지 같아야 할 이유는 없다.
문제는 지금 구조에서는 그렇게 하기가 어렵다는 것이다.
방법론을 프로젝트에 넣으면 안 쓰는 사람에게도 딸려간다.
그렇다고 안 넣으면 같이 써보고 싶은 사람이 찾을 방법이 없다.
쓰는 사람만 쓰고 나머지는 영향받지 않는 중간이 필요했다.
같이 지켜야 할 규칙과 각자 고를 방법은 다르다
물론 각자 마음대로 개발하자는 이야기는 아니다.
코딩 규칙, 시스템 구조, 보안 기준, 빌드 방식처럼 프로젝트에서 합의한 내용은 같이 지켜야 한다. 필수 테스트나 변경 절차가 정해져 있다면 그것도 마찬가지다.
반면 이런 내용은 조금 다르다.
- 작업 크기를 어떻게 나눌지
- 분석을 어떤 순서로 할지
- 설계를 어느 정도까지 할지
- 에이전트에게 어떤 역할을 맡길지
- 독립 리뷰를 몇 번 할지
- 검증을 어떤 순서로 진행할지
이건 프로젝트 자체의 규칙이라기보다 일을 진행하는 방법에 가깝다.
그래서 기준을 하나 잡았다.
프로젝트 공통 규칙
= 프로젝트에 참여하는 사람이 함께 지켜야 하는 것
개발 방법론
= 개발자가 선택해서 사용하는 작업 방식
조금 더 단순하게 말하면,
다른 사람에게도 지키라고 요구할 내용이면 공통 규칙에 있어야 한다.
이 기준이 생각보다 중요했다.
예를 들어 주문 코드를 수정하면 반드시 특정 테스트를 통과해야 한다고 하자.
그게 모든 개발자에게 필요한 절차라면 누군가의 개발 방법론 안에 들어 있으면 안 된다. 프로젝트 공통 규칙이나 주문 영역의 공용 문서에 있어야 한다.
반대로 큰 작업에서는 별도 설계 리뷰를 한 번 더 한다거나, 구현한 에이전트와 다른 에이전트에게 독립 리뷰를 맡긴다는 건 선택해서 사용할 수 있는 방법론에 가깝다.
프로젝트는 사실을 가지고, 방법론은 작업 방식을 가진다
프로젝트 자체에 대한 정보는 실제 프로젝트가 가지고 있어야 한다.
예를 들면 이런 것들이다.
실제 프로젝트
├─ 소스 코드
├─ 업무 문서
├─ 시스템 구조
├─ API 정보
├─ 데이터 구조
├─ 테스트
└─ 프로젝트 공통 규칙
업무 규칙이나 시스템 구조를 방법론 저장소에만 넣어버리면 방법론을 사용하지 않는 개발자는 해당 정보를 알기 어려워진다.
방법론을 강제하지 않으려고 분리했는데, 오히려 다른 방식으로 종속되는 셈이다.
그래서 업무 문서와 시스템 구조는 실제 프로젝트에 두는 편이 맞다고 봤다.
방법론은 대신 이런 내용을 가진다.
개발 방법론
├─ 어떤 문서를 먼저 볼지
├─ 어떤 순서로 분석할지
├─ 어떤 경우 설계를 더 깊게 할지
├─ 어떤 에이전트를 사용할지
├─ 어떤 방식으로 리뷰할지
└─ 무엇을 검증할지
프로젝트는 무엇이 맞는지에 대한 원본을 가지고, 방법론은 그걸 어떻게 다룰지를 정한다.
그렇다고 방법론이 프로젝트와 무관해야 한다는 뜻은 아니다.
특정 프로젝트에 맞게 아주 구체적으로 만들어도 된다고 생각한다. 어떤 문서를 봐야 하는지, 어떤 종류의 변경에서 무엇을 검증해야 하는지까지 알고 있어도 된다.
중요한 건 프로젝트에 맞춘 방법론이라고 해서 모두가 그 방법론을 사용해야 하는 것은 아니라는 점이다.
방법론은 프로젝트 밖에 두고 싶었다
처음에는 방법론 자체를 프로젝트 안에 두는 게 가장 자연스럽다고 생각했다.
그런데 그렇게 하면 프로젝트와 방법론이 너무 강하게 묶인다.
지금 쓰는 방법보다 더 좋은 방법론이 생겼을 때 바꾸기도 어렵고, 같은 파트에서도 누군가는 쓰고 누군가는 사용하지 않는 상황을 표현하기도 애매하다.
그래서 방법론 자체는 별도의 저장소나 위치에 두고, 실제 프로젝트에는 어떤 방법론을 연결해서 사용할 수 있는지에 대한 정보만 남기는 방식을 생각했다.
대략 이런 구조다.
실제 프로젝트
│
├─ 코드
├─ 업무 문서
├─ 시스템 구조
├─ 프로젝트 공통 규칙
│
└─ .agentics/
│
│ 사용할 수 있는 방법론 정보
▼
별도 방법론 저장소
├─ 분석 절차
├─ 설계 절차
├─ 에이전트 구성
├─ 리뷰 방식
└─ 검증 절차
처음에는 .sdd라는 이름을 생각했다.
그런데 각 파트가 어떤 방법론을 쓸지는 알 수 없다.
어떤 파트는 SDD를 쓸 수도 있고, 어떤 파트는 다른 방법론을 쓸 수도 있다. 아예 별도 방법론 없이 개발할 수도 있다.
그래서 일단 특정 방법론 이름에 묶이지 않는 .agentics라는 이름을 생각해봤다.
아직 정해진 규격 같은 건 아니고 아이디어 단계의 이름이다.
.agentics에는 방법론 자체를 넣지 않는다
예를 들어 프로젝트가 이런 구조라고 해보자.
project/
├─ src/
├─ docs/
└─ .agentics/
├─ order.yaml
├─ payment.yaml
└─ notification.yaml
각 파일에는 방법론 전체가 들어가는 것이 아니다.
어떤 방법론을 연결해서 사용할 수 있는지만 적는다.
methodology: adaptive-agentic-sdd
version: 2.1
처음에는 여기에 optional: true 같은 항목도 넣어볼까 했다. 그런데 방법론은 어차피 선택해서 쓰는 것이라 그 값은 항상 true다. 그래서 넣지 않았다.
여기서 중요한 건 연결되어 있다는 것과 실제 사용하는 것은 다르다는 점이다.
같은 프로젝트, 같은 영역을 개발하더라도 한 사람은 이 방법론을 사용할 수 있고 다른 사람은 평소 방식대로 개발할 수 있어야 한다.
.agentics도 결국 프로젝트에 들어가는 파일인데 이것도 일종의 강제 아닌가 하는 생각은 들었다.
맞다. 아무 영향도 없다고 할 수는 없다.
다만 .agentics는 개발 규칙을 강제하기 위한 파일이 아니라 이 프로젝트에서 사용할 수 있는 방법론을 공유하기 위한 연결 정보에 가깝다.
혼자 시험하는 단계라면 이 연결 정보조차 로컬에만 두고 시작해도 된다. 같이 사용할 필요가 생겼을 때 프로젝트에 올려도 된다.
그냥 AGENTS.md에 넣으면 되는 것 아닌가?
여기서 가장 먼저 나올 수 있는 질문이다.
기존 AGENTS.md나 각 도구에서 제공하는 프로젝트 지침 파일에 방법론을 적는 것도 가능하다.
하지만 일부 도구에서는 이런 프로젝트 지침을 작업 시작부터 기본으로 읽는다.
그러면 방법론을 사용하지 않는 사람도 해당 내용을 같이 가지고 작업하게 된다.
파일 안에 “필요하면 사용하세요”라고 적어도, 이미 그 방법론 설명이 작업에 들어와 있는 셈이다.
내가 생각하는 구조는 조금 다르다.
프로젝트 공통 지침
→ 기본으로 적용
.agentics
→ 연결 정보만 제공
외부 방법론
→ 사용하기로 했을 때만 불러옴
즉 파일 이름이 다른 게 중요한 게 아니라,
항상 적용되는 프로젝트 규칙과 필요할 때만 불러오는 개발 방법론을 나누고 싶은 것이다.
도구마다 지침을 읽는 방식은 다를 수 있으니 실제 구현할 때는 사용하는 도구의 동작을 확인할 필요가 있다.
그럼 실제 작업에서는 어떻게 동작할까?
예를 하나 들어보자.
주문 완료 알림이 두 번 발송되는 문제가 생겼다.
개발자는 평소처럼 실제 프로젝트에서 작업을 시작한다.
방법론을 사용하고 싶다면 먼저 이번 작업의 기준이 되는 영역을 선택한다.
주문 완료 알림 중복 발송 수정
↓
작업 영역: notification
↓
.agentics/notification.yaml 확인
↓
연결된 방법론 확인
↓
사용할지 결정
↓
방법론 불러오기
↓
분석 / 설계 / 구현 / 리뷰 / 검증
처음부터 에이전트가 코드를 훑어보고 어느 영역인지 자동으로 맞히게 만들 필요는 없다고 생각한다.
초기에는 개발자가 직접
이번 작업은 알림 영역
정도로 지정하면 충분하다.
실제로 사용해보면서 필요성이 생기면 관련 코드나 업무 문서를 보고 자동으로 작업 영역을 판단하는 기능을 추가할 수 있다.
처음부터 자동 판단까지 만들기 시작하면 해결하려는 문제보다 시스템이 더 커질 수 있다. ㅋㅋ
그리고 한 가지는 확실하게 하고 싶다.
사용하기로 한 방법론을 찾지 못했다면 그냥 일반 방식으로 넘어가면 안 된다.
예를 들어 adaptive-agentic-sdd 2.1을 사용한다고 했는데 해당 방법론을 불러올 수 없다면 작업을 멈추고 알려줘야 한다.
조용히 일반 모드로 넘어가버리면 사용자는 방법론에 따른 분석과 리뷰, 검증이 끝난 줄 착각할 수 있다.
실패한 사실이 보이지 않는 게 오히려 더 위험하다.
주문 코드까지 바꿔야 한다면?
알림 중복 원인을 분석하다 보니 문제의 시작이 주문 처리 쪽에 있을 수도 있다.
결국 알림 코드뿐만 아니라 주문 코드까지 수정해야 하는 상황이다.
그렇다고 주문 영역에서 사용하는 다른 방법론까지 불러와 두 방법론을 동시에 실행할 생각은 없다.
일단 하나의 작업에는 하나의 대표 방법론을 적용하는 쪽이 단순해 보인다.
작업 시작 영역
→ 알림
사용 방법론
→ 알림 영역에서 선택한 방법론
주문 영역
→ 영향 확인 및 필요한 코드 수정
대신 주문 영역에 모든 개발자가 지켜야 하는 규칙이 있다면 그건 그대로 따라야 한다.
예를 들어 주문 코드를 수정하면 반드시 특정 테스트를 돌려야 한다면, 그 내용은 주문 파트의 개인 방법론에 있으면 안 된다.
프로젝트에서 함께 볼 수 있는 공통 규칙에 있어야 한다.
결국 다시 처음 기준으로 돌아간다.
다른 개발자에게도 요구할 내용이라면 방법론이 아니라 공통 규칙에 둔다.
연결했다고 제대로 수행되는 건 아니다
이건 기존 방법론을 만들면서 계속 느꼈던 부분이다.
지침 파일이 있다고 에이전트가 항상 제대로 따르는 것은 아니었다.
스킬 문서가 있다고 필요한 순간에 반드시 실행되는 것도 아니었다.
.agentics도 마찬가지다.
방법론 연결
≠
방법론 수행 보장
이번 구조는 어떤 방법론을 선택하고 어떻게 연결할 것인지를 다루는 것이다.
실제로 독립 리뷰가 수행됐는지, 검증이 빠지지 않았는지, 필요한 절차를 제대로 거쳤는지는 방법론 내부에서 따로 확인해야 한다.
연결과 수행을 같은 문제로 보면 .agentics가 해결해야 할 범위가 끝없이 커진다.
아직 확인해야 할 것들
아직 정하지 못한 부분도 있다.
방법론을 어디서 가져올지부터 정해야 한다.
공개 저장소일 수도 있고, 회사 내부 저장소일 수도 있고, 개발자 로컬에 설치된 방법론일 수도 있다.
외부에서 가져오는 내용을 어디까지 믿을지도 고민해야 한다. 설정 파일에 적혀 있다는 이유만으로 바로 받아서 실행하는 구조는 위험할 수 있다.
방법론이 낡는 문제도 있다.
프로젝트의 문서 구조나 코드 위치가 바뀌었는데 외부 방법론은 예전 내용을 계속 참고하고 있을 수 있다.
없는 파일을 찾는 것은 금방 알 수 있다.
더 위험한 것은 틀렸는데 그럴듯하게 남아 있는 오래된 정보다.
이런 부분은 실제로 적용해보면서 하나씩 확인할 생각이다.
처음부터 모든 저장소와 모든 개발 도구, 모든 방법론을 지원하는 뭔가를 만들 생각은 없다.
그러면 또 일이 너무 커진다. ㅋㅋ
우선 작은 작업부터 붙여보고 지금보다 실제로 편한지, 방법론을 쓰지 않는 사람에게 정말 불필요한 영향을 주지 않는지부터 보면 될 것 같다.
정리
결국 하고 싶은 건 단순하다.
프로젝트에서 모두가 지켜야 할 규칙과, 개발자가 선택해서 사용하는 방법론을 분리하고 싶다.
그리고 방법론은 프로젝트 안에 고정하지 않고 필요할 때 연결해서 사용하고 싶다.
쓰고 싶은 사람은 어떤 방법론이 있는지 찾을 수 있고, 쓰지 않는 사람은 그대로 개발하면 되는 정도면 충분하다.
.agentics는 그 선택을 조금 더 자연스럽게 만들 수 없을까 생각하면서 나온 아이디어다.
아직은 아이디어 단계고, 직접 적용해보면 또 바뀔 가능성이 높다.
아마 그 과정에서 지금 생각하지 못한 문제가 또 나올 것 같다.