두 프로젝트가 같은 문제를 해결하고 있었습니다. 이를 합쳐 하루 만에 npm에 배포했습니다.
Source: Dev.to
번역을 진행하려면 실제 기사 본문이 필요합니다.
위 링크에 있는 전체 텍스트(코드 블록과 URL을 제외한 부분)를 제공해 주시면, 요청하신 대로 마크다운 형식과 기술 용어를 유지하면서 한국어로 번역해 드리겠습니다.
AI 코딩 도구 간 컨텍스트 규칙 관리
문제:
모든 AI‑코딩 도구마다 컨텍스트 규칙을 정의하는 방식이 다릅니다.
- Claude Code →
CLAUDE.md - Cursor →
.cursor/rules - Gemini CLI →
GEMINI.md
두 개 이상의 도구를 사용할 경우, 같은 내용이 세 곳에 각각 약간씩 다른 형식으로 존재하게 되고, 동기화 문제와 끊임없이 싸워야 합니다.
두 개의 병행 시도
| 프로젝트 | 내용 | 부족했던 점 |
|---|---|---|
| DevContext AI | 전체 스택 웹앱 (MCP 서버, Supabase, Vercel, 인증, 버전 관리 규칙) | 실제로 필요했던 것보다 너무 많았고, 나조차 사용하지 않음. |
| dev‑workflows | CLI‑우선 아이디어, YAML에 문서화, 각 편집기 형식으로 컴파일 | 문서 형태만 존재했으며 실행 가능한 코드가 없음. |
두 시도 모두 같은 문제를 해결하려 했지만, 하나는 코드가 너무 많았고 다른 하나는 문서가 너무 많았다.
문서 함정
아직 존재하지 않는 CLI를 위해 다섯 개의 마크다운 파일을 만들게 되었습니다:
VISION_GENERAL.mdARCHITECTURE.mdROADMAP.mdDECISIONS.mdCLI_SPEC.md
문서는 생산적인 것처럼 보였지만, 실제로는 첫 번째 코드를 작성하는 것을 미루는 방법에 불과했습니다.
교훈: 프로젝트를 한 문단으로 설명할 수 없다면, 문제는 문서가 부족해서가 아니라 명확성이 부족해서입니다.
앞으로 나아갈 길 선택
나는 하나의 프로젝트, 즉 CLI를 세 가지 이유로 유지했습니다:
- 구조적 문제: 편집기마다 중복된 규칙이 사라지지 않으며, 각 편집기는 자체 포맷이 필요합니다.
- 보완적인 특성: CLI는 기본 편집기 기능 와 함께 작동하는 반면, 웹앱은 그것들과 경쟁합니다.
- 즉각적인 검증: CLI가 실제 프로젝트에서 동작한다면, 그것이 작동한다는 것을 알 수 있습니다. 웹앱은 온보딩과 유지가 이루어져야 검증할 수 있습니다.
웹앱의 인프라(MCP, Supabase, 버전 관리)는 향후 “Pro” 티어가 될 수 있지만, 현재 우선순위는 작동하고 설치 가능한 도구입니다.
문서를 두 개의 필수 파일로 정리했습니다:
CLI_SPEC.md– 구현 계약서( spec).DECISIONS.md– 의사결정 로그.
다른 모든 파일은 삭제되었습니다.
Claude Code로 CLI 구축
스프린트 1 – 코어 (오전)
-
Scaffold – Claude Code에 생성 요청:
package.jsontsconfig.jsoncommander기반 CLI와 스텁 명령
결과: 몇 분 만에 완료.
-
Implemented
devw init– 프로젝트를 감지하고, 인터랙티브 프롬프트를 실행하며,.dwf/폴더 구조를 생성합니다. -
Implemented
devw compile– 제품의 핵심:- YAML 규칙 파일을 파싱합니다.
- 세 개의 브리지 (Claude, Cursor, Gemini)가 각각 네이티브 포맷으로 변환합니다.
- 적절한 컨텍스트 파일을 생성합니다.
-
Implemented
devw doctor– 모든 것이 정상인지 검증합니다.
스프린트 2 – 블록 (정오)
미리 준비된 블록 시스템을 추가했습니다:
devw add typescript-strict– 엄격한 TypeScript 규칙을 YAML에 주입합니다.- 레지스트리, 설치 프로그램, 6개의 콘텐츠 블록.
- 명령:
add,remove,list. - 테스트: 17개 통과.
스프린트 3 – 배포 (오후)
- README, npm 배포 설정, GitHub Actions CI를 추가했습니다.
- 자동 릴리스를 위한 changesets를 통합했습니다.
- Dogfooding: 자체 레포지토리에서
dev‑workflows를 실행했습니다.
Dogfooding 중 발견된 버그
| Bug | Symptom | Fix |
|---|---|---|
devw init added the whole .dwf/ to .gitignore | 소스 규칙(버전 관리하려는)이 무시되었습니다. | .dwf/.cache/만 무시하도록 수정했습니다. |
| Invalid prompt input caused a stack trace crash | 사용자 경험이 나쁨 – CLI가 다시 프롬프트를 표시하는 대신 충돌했습니다. | 정상적인 오류 처리와 재프롬프트 로직을 추가했습니다. |
이 세 가지 버그는 테스트만으로는 절대 발견되지 않았으며, 실제 사용을 통해 드러났습니다.
End‑of‑Day Result
- npm에 게시됨 (
dev‑workflows). - 명령어 (6):
init,compile,doctor,add,remove,list. - 브리지 (3): Claude Code, Cursor, Gemini CLI.
- 미리 준비된 규칙 블록 (6): TypeScript, React, Next.js, Tailwind, testing, Supabase.
- 테스트: 54개 이상 통과.
- CI: GitHub Actions.
- 릴리스: changesets를 통해 자동화됨.
Quick Usage
# Initialise a project
npx dev-workflows init
# Add a rule block (e.g., strict TypeScript)
npx dev-workflows add typescript-strict
# Generate the context files for each editor
npx dev-workflows compile규칙을 YAML 한 번 정의하면 → 각 편집기용으로 컴파일됩니다.
규칙을 변경하고compile을 다시 실행하세요. 문제가 있으면devw doctor가 알려줍니다.
회고
- Documentation before code는 위장된 미루기일 수 있다.
- concise spec만 있으면 AI가 기능적인 제품을 구현하기에 충분하다.
- Dogfooding은 테스트가 절대 예상하지 못한 문제들을 밝혀낸다.
- Ship first, polish later. 하드코딩된 값, 기본 프롬프트, 그리고 간단한 블록 시스템이라도 도구가 사용 가능하면 괜찮다. 일찍 공개하는 것이 아이디어를 검증하는 가장 빠른 방법이다.
다음은?
- 더 많은 브리지 – Windsurf, Copilot 및 컨텍스트 파일을 사용하는 기타 편집기.
- 원격 블록 레지스트리 – 커뮤니티가 기여한 규칙 블록.
- 감시 모드 –
.dwf/변경 시 자동 재컴파일. - 맞춤 스코프 – 기본 제공 다섯 개를 넘어선 카테고리.
- 프로 웹앱 – 규칙 관리를 위한 시각 UI (향후 티어).
dev‑workflows는 현재 v0.1이며, 기능이 구현되어 내 프로젝트에 사용 중이고 커뮤니티 피드백을 받을 준비가 되었습니다.
Dev‑Workflows
AI 코딩 도구를 관리하기 위한 팀 친화적인 인터페이스로, 버전 관리와 동기화를 지원합니다.
여러 AI 코딩 도구를 사용하면서 중복된 규칙을 유지하는 것이 번거롭다면, 한 번 시도해 보세요:
npx dev-workflows init패키지
- npm:
- GitHub:
- License: MIT
버그를 발견하거나 아이디어가 있으면 이슈를 열어 주세요. 이 프로젝트는 공개적으로 진행되고 있습니다.
필수: Node.js ≥ 22.