Formalized, Reviewed, Triaged — 실무자의 보고, Part II

Source: Dev.to

번역할 텍스트를 제공해 주시겠어요? 텍스트를 받으면 요청하신 대로 한국어로 번역해 드리겠습니다.

Hook

paragraf 프로젝트를 실행하는 워크‑풀 스키마는 spec, package, issue‑bucket이라는 세 가지 작업 유형을 정의합니다. 세 가지 중 두 가지만 정의된 프로세스를 가지고 있습니다.

첫 번째 글에서는 작동하는 라이브러리를 만들기 위한 방법론을 소개했습니다. 그 다음 주에 두 가지 병행 개선이 이루어졌습니다:

1. 두 개의 새로운 색상 관련 패키지를 배포한 스프린트.
2. spec과 package 작업을 모두 처리할 수 있도록 방법론을 공식화.

article‑1에서는 이 방법론이 실천이었지만, 일주일 뒤에는 문서화된 프로세스로 전환되었습니다.

방법론 문서화

docs/
├── methodology.md              # phases, gates, ask‑human triggers
├── methodology-reference.md    # archive procedures, anti‑patterns
├── outer-context.md            # project‑level consistency checker
├── work-pool.md                # work registry + state machine
├── glossary.md                 # defined terms, hierarchy summary
├── dependency.md               # project‑level dependency map
├── io-schemas.md               # project‑level I/O navigation
├── roadmap.md                  # strategy and milestones
├── AI-PRIMER.md                # minimal session bootstrap
│
├── inner-context/[package]/
│   ├── inner-context.md        # role, constraints, package rules
│   ├── io-schema.md            # public types, exported functions
│   ├── dependency.md           # package imports
│   └── decisions.md            # active draft decisions only
│
├── plan/
│   └── workId-package-spec-plan-[YYMMDD-HHMM].md
│
└── archive/
    ├── plan/done/
    ├── plan/cancelled/
    └── decision/[package]-decisions-archive.md

• 각 문서는 하나의 역할만 가집니다.
• methodology.md는 지침 세트(네 단계)입니다.
• outer-context.md는 프로젝트 수준 일관성 검사를 제공합니다.
• work-pool.md는 명시적인 상태 머신을 가진 레지스트리입니다.
• decisions.md는 진행 중인 결정을 보관하며, 최종 확정되면 한 줄 제약으로 전환됩니다.

동기를 부여하는 관찰은 간단합니다: article‑1에서 방법론은 빠른 반복 주기를 견뎌냈으며, 두 개의 컬러 패키지가 이를 통해 배포될 때 새로운 프로세스의 가치를 입증했습니다.

실무에서의 형식화

스프린트 동안 설계가 뒤바뀌는 일이 발생했습니다: OutputIntent를 render‑pdf에 직접 가져오는 원래 선택이 decisions.md에 문서화된 새로운 초안 결정으로 대체되었습니다. 의사결정 라이프사이클은 이를 별다른 절차 없이 처리했으며, 형식화된 프로세스가 뒤바뀜을 원활히 수용할 수 있음을 보여줍니다.

• 테스트가 통과했습니다.
• 엔드‑투‑엔드 실행이 정상적으로 완료되었습니다.

Article‑1 은 단위 테스트가 실패한 감사 순간(excuse-me-kemal-I-forked-up.md)을 설명했습니다. 이후 검토는 그 경험을 바탕으로 진행되었습니다.

검토 프로세스 및 발견 사항

네 가지 발견 카테고리

5단계 검토 워크플로

1. Whole‑codebase review by Claude Opus – 코드베이스가 검토 환경에 업로드되었습니다.

2. Cross‑check and addition by VS Code Copilot – Copilot이 발견 사항을 추가하고 우선순위를 수정했으며 범위를 좁혔습니다.

3. Batched fixes by VS Code Copilot – 항목들을 그룹화하고 수정했습니다.

4. GitHub Copilot review on diffs, then Copilot fixes – 세 번 실행:

   gh pr view --json reviews,comments \
     --jq '.reviews[].body, .comments[].body' \
     > docs/findings-I.md

   findings-I.md, findings-II.md, findings-III.md가 각각 댓글 수 7, 11, 6개로 생성되었습니다. 각 파일을 검토하고 문제를 수정했습니다.

5. Final structural pass by Opus – 업데이트된 코드베이스가 구조 및 아키텍처 검토를 위해 반환되었습니다.

전체 약 105개 발견은 두 출처에서 나왔으며, Opus에서 81개, 나머지는 Copilot에서 나왔습니다. 문서화된 방법론은 그 결과물과 대조하여 검증할 수 있습니다.

Issue‑Bucket 격차

작업‑풀 스키마는 세 가지 작업 유형을 명시합니다: spec, package, 그리고 issue‑bucket. spec와 package 작업은 정의된 프로세스를 가지고 있지만, issue‑bucket 작업은 전혀 없습니다. 이 유형은 일급 엔트리로 존재하지만 공식적인 라이프사이클이 부족합니다.

구체적인 예: 검토 중에 @paragraf/render-pdf와 @paragraf/compile에 대한 발견이 생성되었습니다. 문제는 장치가 아니라 운영자의 머리 속에서 발생했습니다. 이는 조판과 타이포그래피의 차이와 직접 연결되며, 위 표에서 논의된 “거짓 안심 테스트”를 반영합니다.

이 격차는 형식화의 실패가 아니라; 어떤 프로세스든지 갖는 솔직한 한계를 반영합니다. 원래 81개 항목 중 22개가 아직 열려 있지만, 이는 잔여물이 아니라 명시적인 issue‑bucket 루프의 필요성을 강조합니다.

결론

일주일에 두 가지 개선—정형화된 방법론 아래 두 개의 새로운 패키지를 출시—은 프로세스가 실천에서 문서화된 절차로 확장될 수 있음을 보여줍니다. 교훈은 paragraf를 넘어섭니다: 장기 개발을 지속하는 모든 LLM‑지원 시스템은 명확하고 서면화된 방법론의 혜택을 받습니다.

이 시리즈의 다음 기사에서는 issue‑bucket loop가 종료되면 이를 다룰 것입니다. paragraf 저장소, 라이브 데모, 그리고 기사 시리즈는 오픈 소스입니다:

github.com/kadetr/paragraf