context-driven-development

context-driven-development 스킬 개요

context-driven-development 스킬이 하는 일

context-driven-development 스킬은 conductor/ 디렉터리에 프로젝트 컨텍스트 아티팩트를 소수의 핵심 문서로 정리·유지하도록 도와줘, AI 보조 개발이 흔들리지 않는 재사용 가능한 기반 위에서 진행되게 합니다. 매번 채팅마다 프로젝트를 다시 설명하는 대신, product.md, tech-stack.md, workflow.md, tracks.md 같은 핵심 문서를 정의해 두고 프로젝트가 바뀔 때마다 함께 갱신하는 방식입니다.

어떤 사람에게 잘 맞는가

이 스킬은 Conductor 스타일 워크플로, 여러 세션에 걸친 AI 개발, 또는 프롬프트가 바뀌어도 프로젝트 의도·기술 스택·작업 추적이 일관되게 유지되어야 하는 팀 환경에 특히 잘 맞습니다. 특히 다음과 같은 경우 유용합니다.

• 새 프로젝트 초기 세팅
• 기존 코드베이스에 AI 에이전트를 온보딩할 때
• 반복 가능한 프로젝트 컨텍스트를 팀 차원에서 만들고 싶을 때
• 세션이 바뀔 때마다 컨텍스트가 끊기는 데 지친 사용자

실제로 해결하는 핵심 문제

대부분의 사용자는 “문서를 더 많이” 원하는 것이 아닙니다. 원하는 것은 AI 출력이 더 이상 엇나가지 않는 상태입니다. context-driven-development의 실질적인 역할은 세션 안에만 머무는 모호한 프로젝트 지식을, 구현 작업·계획 수립·인수인계 전반에서 살아남는 관리 가능한 아티팩트로 바꾸는 데 있습니다.

일반적인 프롬프팅과 다른 점

일반 프롬프트는 앱 설명을 한 번 적어 넣는 데 그치기 쉽습니다. 반면 context-driven-development skill은 그 설명을 시간이 지나도 최신 상태로 유지하고, 문서 간 내용이 서로 충돌하지 않도록 관리하는 구조를 제공합니다. 차별점은 단순한 코드 생성이 아니라, 개발 전과 개발 중에 필요한 컨텍스트 구조화와 동기화에 있습니다.

잘 맞을 때 얻는 것

context-driven-development for Context Engineering을 도입했을 때 가장 큰 효과는 연속성이 좋아진다는 점입니다.

• 제품 의도가 더 명확해짐
• 스택 선택 이유가 문서화됨
• 개발 워크플로 기대치가 명시됨
• 흩어진 TODO 대신 추적 가능한 작업 단위가 생김
• 기존 레포지토리에도 에이전트 온보딩이 쉬워짐

잘 맞지 않는 경우

한 번 쓰고 끝낼 코드 스니펫만 필요하거나, 프로젝트 문서를 유지할 생각이 없거나, 지속적인 컨텍스트가 이후 출력 품질에 도움이 되지 않는 워크플로라면 이 스킬은 건너뛰는 편이 낫습니다. 같은 프로젝트를 반복해서 다루는 상황일수록 가치가 커집니다.

context-driven-development 스킬 사용 방법

설치 맥락과 이 스킬의 위치

이 스킬은 wshobson/agents 저장소의 plugins/conductor/skills/context-driven-development 경로에 있습니다. Skills 지원 환경에서의 기본 설치 방식은 다음과 같습니다.

npx skills add https://github.com/wshobson/agents --skill context-driven-development

설치 후에는 바로 구현으로 들어가기보다, 프로젝트 컨텍스트를 새로 만들거나 갱신해야 할 때 AI 환경에서 호출해 사용하는 것이 적절합니다.

처음 쓰기 전에 먼저 읽어야 할 파일

빠르게 시작하면서 추측을 줄이려면 먼저 아래 파일을 읽는 것이 좋습니다.

1. plugins/conductor/skills/context-driven-development/SKILL.md
2. plugins/conductor/skills/context-driven-development/references/artifact-templates.md

SKILL.md에는 이 스킬을 언제 써야 하는지, 아티팩트 간 관계가 어떻게 이어지는지, 어떤 유지보수 흐름을 따르는지가 설명되어 있습니다. references/artifact-templates.md는 실무적으로 특히 유용한 파일로, product.md, tech-stack.md 등 각 문서가 어떤 형태를 가져야 하는지 보여주기 때문에 에이전트에 완성도 높은 입력을 더 빠르게 줄 수 있습니다.

context-driven-development 스킬에 필요한 입력

이 스킬은 컨텍스트 아티팩트를 생성하거나 갱신할 만큼의 근거 자료가 있을 때 가장 잘 작동합니다. 좋은 입력에는 보통 다음이 포함됩니다.

• 프로젝트 유형: greenfield 또는 brownfield
• 현재 저장소 또는 폴더 구조
• 제품 목적과 타깃 사용자
• 기술적 제약과 스택 선택
• 선호하는 개발 워크플로
• 현재 로드맵, 마일스톤, 작업 항목
• README.md, 티켓, 아키텍처 노트, 코드 같은 기존 자료

“내 앱용 컨텍스트 세팅해줘” 정도로만 말하면 결과는 대체로 일반론에 머뭅니다. 제품, 스택, 워크플로, 기존 레포지토리의 근거까지 함께 주면 아티팩트가 실제로 활용 가능한 수준으로 구체화됩니다.

Greenfield 사용법: 새 프로젝트 시작할 때

새 프로젝트에서는 코드를 본격적으로 쓰기 전에 context-driven-development로 핵심 아티팩트를 먼저 골격화하는 것이 좋습니다. 좋은 요청에는 다음이 들어갑니다.

• 제품이 무엇인지
• 누구를 위한 것인지
• 핵심 기능 중 범위에 포함되는 것과 제외되는 것
• 예상 기술 스택
• 배포와 테스트에 대한 기대치
• 작업을 어떤 방식으로 추적할지

이 단계에서 특히 가치가 큰 이유는, 구현이 시작되기 전까지 흐릿하게 남아 있기 쉬운 결정들을 미리 명확하게 만들기 때문입니다.

Brownfield 사용법: 기존 레포에서 컨텍스트 추출하기

기존 코드베이스라면, 저장소를 바탕으로 컨텍스트를 추론하고 구조화해 달라고 요청하면 됩니다. 특히 다음을 근거로 삼게 하세요.

• 소스 트리
• 의존성 파일
• CI 설정
• README와 이슈 히스토리
• 기존 문서
• 네이밍 규칙과 워크플로 단서

많은 사용자가 여기서 빠르게 도입 효과를 체감합니다. context-driven-development guide는 “동작은 하지만 설명하기 어려운” 레포를, 이후 에이전트가 재사용할 수 있는 아티팩트로 바꿔 주는 데 강합니다.

핵심 아티팩트와 각 문서의 역할

이 저장소는 conductor/ 안의 몇 가지 지속성 있는 파일을 중심으로 돌아갑니다.

• product.md: 문제, 사용자, 솔루션, 기능, 지표, 로드맵
• tech-stack.md: 언어, 프레임워크, 의존성, 인프라, 도구
• workflow.md: 개발이 어떤 방식으로 진행되어야 하는지
• tracks.md: 작업 단위, 상태, 진행 중인 전달 체계

핵심은 파일을 만드는 것 자체가 아니라, 파일들 사이의 관계를 맞추는 데 있습니다. 제품 결정은 스택 선택과 어긋나지 않아야 하고, 워크플로 규칙은 팀의 실제 운영 방식과 맞아야 하며, 추적 중인 작업은 로드맵과 구현 우선순위에 연결되어야 합니다.

막연한 목표를 강한 호출 문장으로 바꾸기

약한 프롬프트:

• “Use context-driven-development for my project.”

더 강한 프롬프트:

• “Use context-driven-development to create initial conductor/ artifacts for a brownfield SaaS repo. Infer product scope from README.md, src/, and issue labels. Capture stack choices from package.json, Docker config, and CI. Create product.md, tech-stack.md, workflow.md, and tracks.md. Flag assumptions separately from confirmed facts.”

왜 이 요청이 더 잘 작동하나:

• 레포의 현재 상태를 명시함
• 목표 아티팩트를 지정함
• 어떤 자료를 근거로 볼지 알려줌
• 추정과 사실을 분리해 달라고 요청함

처음 도입할 때 추천하는 워크플로

실전적인 context-driven-development usage 흐름은 다음과 같습니다.

1. 레포와 문서에서 현재 근거 자료를 모읍니다.
2. 스킬에 핵심 conductor/ 아티팩트 초안을 만들게 합니다.
3. 사실 오류와 빠진 제약이 없는지 검토합니다.
4. 제품, 스택, 워크플로 문서 사이의 충돌을 정리합니다.
5. 그다음에야 해당 아티팩트에 의존하는 구현 또는 계획 작업을 시작합니다.
6. 범위, 아키텍처, 워크플로가 크게 바뀌면 스킬을 다시 실행합니다.

이 순서가 중요한 이유는, 이 스킬의 목적이 문서를 한 번 생성하는 데 있지 않고 그 이후 작업의 품질을 높이는 데 있기 때문입니다.

아티팩트 템플릿을 잘 활용하는 법

references/artifact-templates.md는 스킬이 가진 정보가 불완전할 때 특히 유용합니다. 에이전트가 비어 있는 섹션을 임의로 만들어 내게 두기보다, 템플릿 항목에 대해 직접 답을 제공하세요. 예를 들면 다음과 같습니다.

• 타깃 페르소나
• 기능 상태
• 성공 지표
• 의존성 선택 이유
• 호스팅 방식
• 테스트와 린트 도구 체인

템플릿을 실제 제약으로 많이 채워 넣을수록, 나중에 손봐야 할 양이 줄어듭니다.

출력 품질을 실제로 바꾸는 실전 팁

더 나은 context-driven-development usage 결과를 얻으려면 다음을 권장합니다.

• 모르는 사항은 명시적으로 표시하라고 요청하기
• 현재 상태와 원하는 미래 상태를 분리하기
• 각 결정이 확정인지, 잠정인지, 미정인지 알려주기
• workflow.md가 중요하다면 팀 워크플로 예시를 제공하기
• 아티팩트를 받아들이기 전에 일관성 점검을 요청하기

특히 유용한 패턴은 “초안을 만든 뒤, 파일 간 모순이 없는지 검증해라”입니다. 이렇게 하면 로드맵은 모바일 앱을 약속하는데 스택과 워크플로는 웹 전용 MVP를 전제하는 식의 불일치를 잡아낼 수 있습니다.

context-driven-development 스킬 FAQ

이미 프롬프트를 잘 쓰는데도 context-driven-development를 설치할 가치가 있나

대체로 그렇습니다. 같은 프로젝트를 자주 다시 다룬다면 특히 그렇습니다. 좋은 프롬프트는 한 세션 안에서는 효과적이지만, context-driven-development skill은 이후 프롬프트가 처음부터 다시 쌓지 않아도 되는 지속성 있는 컨텍스트를 만들어 줍니다.

초보자도 쓰기 쉬운가

그렇지만, 기본적인 프로젝트 질문에는 답할 준비가 되어 있어야 합니다. 이 스킬이 제공하는 것은 구조이지, 사업적 명확성 자체는 아닙니다. 프로젝트 목표가 아직 모호한 초보자라면 사용자, 기능, 제약을 더 구체적으로 정의하기 전까지는 결과물도 다소 일반적으로 나올 수 있습니다.

Conductor에서만 쓸 수 있나

Conductor 스타일의 컨텍스트 아티팩트를 전제로 설계되었기 때문에 가장 잘 맞는 환경은 Conductor 계열입니다. 그래도 방법론 자체는 이식 가능합니다. 제품, 스택, 워크플로, 작업 추적 문서를 구조화하는 방식은 다른 AI 보조 개발 환경에서도 도움이 됩니다.

이 스킬의 가장 큰 한계는 무엇인가

이 스킬이 구현 전문성이나 시스템 설계 리뷰를 대신해 주지는 않습니다. context-driven-development는 프로젝트 컨텍스트를 정리하고, 아티팩트 사이의 관계를 드러내며, 문서가 실제 작업과 어긋나지 않게 맞추는 데 가장 강합니다.

README만 잘 관리하는 것과는 어떻게 다른가

README는 보통 외부 독자나 사용자 관점에서 넓게 설명하는 문서입니다. 이 스킬은 개발 운영에 필요한 컨텍스트를 더 직접적으로 다룹니다. 즉, 제품이 무엇인지, 왜 이 스택을 택했는지, 작업은 어떻게 흘러가는지, 에이전트 세션이 달라져도 무엇이 일관되게 유지되어야 하는지를 문서화하는 쪽에 가깝습니다.

언제 context-driven-development를 쓰지 말아야 하나

작고 금방 버릴 실험, 일회성 스크립트, 또는 아티팩트를 유지할 생각이 없는 프로젝트에는 쓰지 않는 편이 낫습니다. 이 스킬의 가치는 첫 초안 자체보다, 그 이후의 재사용과 동기화에서 나옵니다.

context-driven-development 스킬을 더 잘 활용하는 법

바람이 아니라 근거를 주기

품질이 가장 크게 좋아지는 지점은, 스킬을 실제 레포 근거와 이미 내려진 결정에 단단히 묶어 주는 것입니다. 실제 파일, 설정, 기능 목록을 첨부하거나 참조하세요. 포부만 전달하면 결과물은 살아 있는 작업 컨텍스트가 아니라 흔한 기획 문서처럼 흐르기 쉽습니다.

확정 사실과 추론된 가정을 나눠 달라고 요청하기

자주 발생하는 실패 패턴 중 하나는 레포에서 확인된 사실과 추측이 뒤섞이는 것입니다. context-driven-development 결과를 개선하려면 두 층위로 나눠 달라고 요청하세요.

• 파일이나 문서에서 확인된 내용
• 패턴이나 누락 정보를 바탕으로 추론한 내용

이렇게 해 두면 검토 속도가 훨씬 빨라지고, 무심코 컨텍스트가 어긋나는 위험도 줄어듭니다.

각 아티팩트를 ‘결정 중심’으로 조이기

사용자가 가장 중요하게 보는 것은, 이 아티팩트가 이후 코딩 세션에 실제로 도움이 되느냐입니다. 그러려면 각 파일이 결정을 뒷받침하는 구조여야 합니다.

• product.md: 누구를 위한 것인지, 어떤 문제를 푸는지, 범위, 성공 지표
• tech-stack.md: 어떤 도구를 선택했는지, 그리고 왜인지
• workflow.md: 변경이 어떻게 제안되고, 구현되고, 테스트되고, 리뷰되는지
• tracks.md: 지금 진행 중인 것, 막힌 것, 다음으로 올 것, 완료된 것

미래의 코딩 결정을 안내하지 못하는 섹션이라면 과감히 덜어내는 편이 낫습니다.

결과를 믿기 전에 일관성부터 검증하기

다음과 같은 모순을 점검하게 하면 이 스킬은 훨씬 유용해집니다.

• 제품 범위가 로드맵을 넘어서는 경우
• 스택 선택이 배포 제약과 충돌하는 경우
• 워크플로 기대치가 레포 도구 체인으로 뒷받침되지 않는 경우
• tracks.md가 현재 우선순위와 맞지 않는 경우

이 검증 단계는 context-driven-development for Context Engineering에서 가장 가치가 큰 습관 중 하나입니다.

레포를 어떻게 읽을지까지 프롬프트에 넣기

“내 레포를 분석해줘”라고만 하지 말고, 어디에 사실이 있는지 구체적으로 지정하세요. 예를 들면:

• “Use package.json, Dockerfile, .github/workflows/, and README.md as primary evidence.”
• “Treat issue labels and milestone names as workflow clues.”
• “Prefer explicit config over naming heuristics.”

이렇게 하면 존재하지 않는 스택 정보나 프로세스 세부사항을 지어내는 위험을 줄일 수 있습니다.

첫 초안 전에 완벽을 추구하지 말고, 초안 이후에 반복 개선하기

좋은 패턴은 draft -> review -> refine 입니다. 먼저 완전한 아티팩트를 만들게 한 다음, 두 번째 패스로 다음과 같은 보완을 요청하세요.

• 일반론적인 문장 제거
• 빠진 제약 추가
• 가정을 질문 형태로 전환
• tracks.md를 로드맵에 맞게 정렬
• 알고 있는 경우 정확한 버전 기준으로 스택 선택 이유 보강

첫 프롬프트를 완벽하게 만들려고 애쓰기보다, 이런 식의 반복 개선이 보통 더 좋은 결과를 냅니다.

프로젝트가 바뀌면 아티팩트도 살아 있게 유지하기

context-driven-development install 결정은 문서가 계속 최신 상태일 때만 제대로 값어치를 합니다. 다음과 같은 상황에서는 스킬을 다시 실행하거나 문서를 재점검하세요.

• 아키텍처가 바뀔 때
• 우선순위가 이동할 때
• 도구 체인이 바뀔 때
• 온보딩 마찰이 커질 때
• 에이전트 출력이 실제 프로젝트와 점점 어긋나기 시작할 때

오래된 컨텍스트는 없는 것보다 더 나쁠 수 있습니다. 그럴듯해 보여도 잘못된 확신을 만들기 때문입니다.