Insights
AI가 자동으로 큐레이션·번역·정리하는 기술 동향 피드입니다.
이 문서는 Claude를 활용하여 설계서(요구사항, 기본/상세 설계)를 Markdown 형식으로 작성하고, 이를 스크립트를 통해 Excel로 변환하는 프로세스를 설명합니다. 정본은 GitLab의 Markdown 파일이며, AI가 생성한 내용을 사람이 검토 및 수정하는 워크플로우를 강조합니다.
AI 자동 생성 콘텐츠
본 콘텐츠는 Qiita AI의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기설계서는 Claude가 자료를 바탕으로 Markdown 형식으로 작성하고, 스크립트를 통해 Excel로 변환하여 제출합니다. 정본(正本)은 GitLab에 저장된 Markdown 파일만 사용하며, Excel은 Markdown에서 언제든지 다시 만들 수 있는 사본으로 취급합니다.
Excel 측의 수정을 '지적' 형태로 받는 이 운영 방식은 아직 팀 차원에서 합의되지 않은 제안(마츠모토)입니다. 이전에 결정했던 'Excel과 Markdown 중 어느 쪽에서든 수정 가능(안 A)'과 상충되므로, 이 부분만 먼저 결정할 필요가 있습니다.
문장은 natural-japanese 규칙에 따라 작성했습니다. 제가 사용하는 환경에서는 첨부된 자동 검사가 작동하지 않아 수동 체크리스트로 확인하고 있습니다.
설계서는 Claude가 자료를 바탕으로 Markdown 형식으로 작성하고, 스크립트를 통해 Excel로 변환하여 제출합니다. 정본은 GitLab에 저장된 Markdown 파일만 사용하며, Excel은 Markdown에서 언제든지 다시 만들 수 있는 사본으로 취급합니다.
사양서, 업무 흐름, 기존의 Excel, 회의록 등을 Claude에게 읽히게 합니다. 정해진 형식으로 준비할 필요는 없습니다. Claude는 확정된 정보만을 추출하고, 미확정된 내용은 '미결 사항' 표에 배치합니다.
Claude는 스킬(AI 작업 지시)과 템플릿에 따라 요구사항 정의서, 기본 설계서, 상세 설계서를 작성합니다. 상세 설계서는 화면별로 1개의 파일입니다. 세 문서는 REQ-001이나 SCR-001 같은 ID로 연결되어 있어, 요구사항부터 화면까지 추적할 수 있습니다.
문장의 표현과 판단은 사람이 수정하며, GitLab의 MR(리뷰 요청)을 통해 확인한 후 반영합니다.
변환은 design-doc-sync라는 변환 규칙에 따라 스크립트가 수행합니다. AI가 다시 작성하는 것이 아니므로, 변환 과정에서 내용이 변경될 염려는 없습니다. Excel 표지에는 원본 Markdown의 버전을 기재합니다. 완성된 Excel은 SharePoint에 보관하여 제출에 사용합니다.
상대방 측에서 Excel에 말풍선을 붙이거나 직접 수정했을 경우, 먼저 변경점을 Claude에게 목록화하도록 합니다. 이를 사람이 확인한 후 Markdown에 반영하고, Excel을 다시 만듭니다. Excel을 정본으로 삼지 않는 이유는 두 파일을 병행하여 수정할 경우 어느 것이 최신 버전인지 알 수 없기 때문입니다.
Excel 측의 수정을 '지적' 형태로 받는 이 운영 방식은 아직 팀 차원에서 합의되지 않은 제안(마츠모토)입니다. 이전에 결정했던 'Excel과 Markdown 중 어느 쪽에서든 수정 가능(안 A)'과 상충되므로, 이 부분만 먼저 결정할 필요가 있습니다.
설계서 파일은 GitLab 리포지토리 1곳에 모아둡니다. AI에게 지시(스킬)와 설계서 본문을 같은 장소에 두면, Claude가 매번 동일한 절차와 템플릿으로 작성할 수 있습니다.
（리포지토리）/
├── CLAUDE.md … 「@AGENTS.md」의 1줄만
├── AGENTS.md … 프로젝트 목차. AI가 가장 먼저 읽음
...
Excel은 GitLab에 두지 않고 SharePoint에 둡니다. Markdown에서 언제든지 다시 만들 수 있기 때문에 Git으로 버전을 관리할 필요가 없기 때문입니다.
※안의 2곳은 현재 샘플과는 별도의 zip(설계서 포맷, MD와 Excel 왕복 실증)에 들어 있습니다. 실제 프로젝트에서는 위처럼 모아서 리포지토리에 넣는 것을 제안합니다.
여기에 적는 것은 자료의 위치, ID 지정 방법, AI에게 약속하는 세 가지뿐입니다. 자세한 내용은 docs/에 작성하고, AI는 ID로 검색하여 필요한 부분만 읽습니다. 전체 내용을 매번 읽게 하지 않음으로써 토큰 소모를 줄일 수 있습니다.
| ID 종류 | 형식 | 예시 |
|---|---|---|
| 요구사항 | REQ-세자리번호/비기능 NFR-세자리번호 | REQ-001, NFR-004 |
| ... | ||
| 기술은 4가지입니다. 3가지는 설계서를 작성하기 위한 것이고, 1가지는 Excel로 변환하기 위한 것입니다. |
| 기술 | 사용 장면 | 주요 절차 |
|---|---|---|
| write-requirements | 회의록이나 청취 메모에서 요구사항 정의서 만들기/수정하기 | 자료를 「어려운 점・하고 싶은 것・결정된 것・결정되지 않은 것」으로 나누고, 요구사항에 REQ-xxx를 부여함 |
| ... | ||
| 모든 기술에 공통되는 규칙이 하나 있습니다. 모르는 것은 추측해서 채우지 않고, 미결 사항(Q-xxx) 표에 적는 것입니다. |
기술이 「작성 방법」인 것에 반해, 에이전트는 「누가 할 것인가」를 결정합니다. 역할별로 사용할 도구를 제한하고 있습니다.
| 에이전트 | 역할 | 가능한 일 |
|---|---|---|
| req-analyst | 요구사항 정의 담당 | 자료를 읽고, 요구사항 정의서를 작성함 |
| ... | ||
| design-reviewer가 파일을 변경할 수 없도록 한 것은, 작성하는 역할과 확인하는 역할을 분리하기 위함입니다. AI의 리뷰 결과는 지적 목록으로 받고, 수정할지 여부는 사람이 결정합니다. |