이득:
- AI를 사용하여 대상 고객과 소스를 기반으로 README, Docstring 및 변경 로그 초안을 생성하는 기능
- 문서에서 '무엇/어떻게'와 '왜' 계층을 분리하고 인간으로서 '왜'를 추가하는 기능
- 직접 실행하여 설치 단계를 확인하고 코드 변경의 일부로 문서를 작성
소프트웨어에서 가장 자주 무시되지만 가장 오래 지속되는 부분은 문서입니다. 몇 달이 지나도 코드를 읽을 수 있습니다. 쓴 사람은 사라지고, 맥락은 잊혀지고, 쓴 내용만 남는다. 좋은 README(프로젝트가 무엇인지, 설치 및 실행 방법을 설명하는 소개 문서), 설명 코드 주석 및 최신 API 문서(인터페이스 사용 방법을 설명하는 참조)가 팀의 속도를 직접적으로 결정합니다. AI는 문서에서 많은 "작성 피로"를 없애지만 함정이 따릅니다. AI는 코드에서 자신이 수행하는 작업을 추론할 수 있지만 왜 그런 식으로 수행되었는지 알 수 없는 경우가 많습니다.
이번 단원에서는 README, 코드 주석, docstring(함수/클래스별로 작성된 주석 블록), API 문서 및 변경 로그를 AI로 생성하는 방법을 학습합니다. 그리고 문서의 가장 귀중한 부분인 "왜"를 인간적으로 보존하는 방법.
'무엇'과 '왜'의 구별
문서에는 두 가지 계층이 있습니다. 첫 번째는 무엇/방법입니다: "이 함수는 목록을 정렬합니다", "설치하려면 이 명령을 실행합니다". 이는 코드와 구조에서 추출할 수 있습니다. AI는 여기서 탁월합니다. 둘째, 왜: "이 서비스를 동기식 대신 비동기식으로 만든 이유는 무엇입니까?", "이 제한 값이 30초인 이유는 무엇입니까?", "다른 라이브러리 대신 이 라이브러리를 선택한 이유는 무엇입니까?" 이는 코드에 기록되지 않습니다. 그것은 디자인 결정, 제약, 과거의 고통의 산물입니다.
AI는 "이유"를 모릅니다. 기껏해야 합리적인 추측에 불과합니다. 이는 위험합니다. 왜냐하면 잘못된 이유는 전혀 이유가 없는 것보다 더 나쁘기 때문입니다. 따라서 노동 분업은 명확합니다. AI가 "무엇/어떻게" 초안을 작성하고 "왜"를 추가합니다. 가장 가치 있는 의견은 코드가 말할 수 없는 것을 말하는 것입니다.
팁: 코드 자체에서 명확하게 말하는 내용을 주석으로 반복하지 마세요(예: i = i + 1 // i를 1씩 증가). AI는 때때로 그러한 중복된 설명을 생성합니다. 그런 것들을 제거하고 "왜"라는 말을 하는 데 에너지를 쏟으십시오.
단계별: AI를 사용한 문서 생성
- 대상 고객을 지정합니다. "막 시작한 개발자", "이 API를 사용할 외부 팀", "미래의 나" 등 청중이 언어와 깊이에 대한 분위기를 설정합니다.
- 소스를 제공하세요. 관련 코드, 기존 README, 예제 사용법을 프롬프트에 추가합니다. 출처가 없는 문서는 조작에 대한 초대입니다.
- 부과 구조. README(목적, 설치, 사용법, 구성, 기여)에 대한 표준 섹션, Docstring의 프로젝트 형식입니다.
- "이유" 공백을 표시하십시오. AI에게 근거를 알 수 없는 결정에 대해 "여기에 '왜' 메모가 필요한지"로 표시하도록 요청하세요. 그런 다음 그 빈칸을 채우세요.
- 확인하다. 실제로 설치 단계를 실행하십시오. 샘플 코드를 사용해 보세요. 작동하지 않는 README는 README가 전혀 없는 것보다 더 나쁩니다.
미니 케이스 3개
사례 1 — README 가속화된 온보딩. 오픈 소스 도구의 README가 누락되었습니다. 새로운 기여자들은 평균 2시간 동안 설치에 어려움을 겪었습니다. 팀은 설치 스크립트와 package.json을 AI에 제공하고 구조화된 README 초안을 작성한 다음 깨끗한 시스템에서 단계 자체를 실행하고 누락된 종속성 2개를 추가했습니다. 후속 기여자의 설치 시간은 평균 25분으로 단축되었습니다.
사례 2 - 만들어진 "왜" 함정. 개발자가 AI에 타임아웃 값(타임아웃=30) 옆에 코멘트를 요청했습니다. AI는 "높은 네트워크 대기 시간을 허용하기 위해" 합리적이지만 잘못된 정당화를 작성했습니다. 실제 이유는 다운스트림 서비스의 계약상 30초 제한 때문이었습니다. 이러한 잘못된 해석으로 인해 후속 개발자가 불필요하게 가치를 높이게 되어 사고가 발생하게 되었습니다. 교훈: 코드 소유자는 정당성을 확인해야 합니다.
사례 3 - Docstring 표준이 자동화되었습니다. 40개의 기능을 가진 보조 모듈에는 독스트링이 없었습니다. AI에는 프로젝트 형식(Google 스타일)이 부여되었으며 각 기능에 대한 매개변수, 반환 및 예외 설명이 생성되었습니다. 개발자는 이를 검토하고 몇 가지 잘못된 유형 선언을 수정했습니다. 40가지 기능을 문서화하는 시간이 약 반나절에서 한 시간으로 단축되었습니다.
복사 가능한 템플릿 4개
구조화된 README 초안:
타겟층: {{예: new contributor}}.아래 파일을 기반으로 초안 README를 작성합니다. 섹션: 목적, 기능, 요구 사항, 설치, 운영, 구성, 테스트, 기여. 실제 파일에서 설치/실행 명령을 추출합니다. 입어 보기. 확실하지 않은 장소는 "[VERIFY]"로 표시하세요. 출처: {{package.json / scripts / 샘플 코드}}
독스트링/API 참조:
{{프로젝트 스타일: Google/NumPy/JSDoc}} 형식(간단한 요약, 매개변수(유형 + 의미), 반환, 발생한 예외, 1개의 짧은 예)으로 이러한 함수에 독스트링을 작성합니다. 코드에서 명확하게 말하는 내용을 반복하지 마세요. "이유"가 필요한 디자인 결정은 "[왜 필요한가]"로 표시하고 조작된 근거를 작성하지 마세요.{{코드}}
"이유" 설명에 대한 공백을 제거하십시오.
이 코드에서 다음 개발자는 "이게 왜 그럴까요?"라고 물을 수 있습니다. (마법의 숫자, 특이한 결정, 해결 방법) 각각에 대해 SKELETON에 대한 설명을 제공하고 근거는 공백으로 두십시오. 사유를 작성하겠습니다.{{code}}
변경 내역/PR 성명:
아래 차이점에서 {{changelog 항목 / PR 설명}}을 작성하세요. 형식: 변경된 내용(사용자 언어), 이유(문제: {{...}}), 주요 변경 사항(있는 경우), 테스트되었습니까? 대상 고객에 맞게 기술 전문 용어를 조정하세요.{{diff}}
약한 프롬프트 / 강한 프롬프트
약함: "이 프로젝트에 대한 README를 작성하세요."
Strong: "대상: 이 저장소를 처음으로 복제하는 개발자. 첨부된 package.json, docker-compose.yml 및 scripts/ 폴더를 기반으로 목적, 요구 사항, 설치, 운영, 테스트, 기여 섹션이 포함된 README 초안을 작성합니다. 이 파일에서 명령을 추출하고, 구성하지 말고, 확실하지 않은 부분은 [VERIFY]로 표시하세요."
강력한 버전은 청중, 소스, 구조 및 "만들고 표시" 규칙을 제공합니다. 문서가 실제 파일을 기반으로 작성되었으며 검증할 위치가 명확하게 표시되도록 합니다.
문서 유형
AI는 잘한다
사람이 추가/확인
읽어보기 설치
단계 개요
단계를 실행하고 확인하세요.
독스트링/API
구조, 매개변수, 유형
올바른 유형과 '이유'
코드 주석
"그 사람이 하는 일" 요약
"왜 이래?" 정당화
변경 내역/홍보
초안
영향과 정확성
아키텍처 결정(ADR)
해골
실제 결정과 타협
문서에는 유지 관리가 필요합니다
문서의 가장 위험한 측면은 그것이 거짓임에도 불구하고 사실처럼 보일 때입니다. 코드가 변경되고 문서가 업데이트되지 않으면 독자를 오도하게 됩니다. AI로 쉽게 업데이트할 수 있습니다. 차이점을 발행하고 "이 변경 사항이 문서의 어느 부분에 영향을 미치나요?"라고 물어보세요. 당신은 물어볼 수 있습니다. 그러나 최신성을 보장하는 프로세스는 문서 업데이트를 코드 변경의 일부로 만듭니다(PR의 승인 기준). AI가 가속화됩니다. 팀은 규율을 구축합니다.
주의: README에서 설치 단계를 확인하지 않고 게시하지 마십시오. "아마도 작동할 것 같은" 문서는 새로운 개발자의 첫날을 망치고 신뢰를 약화시킬 수 있습니다. 깨끗한 환경에서 직접 단계를 실행하세요.
일반적인 실수
- AI에 적합한 "이유"를 파악합니다. 거짓 정당화는 정당화가 없는 것보다 더 나쁘다. 코드 소유자는 설계 이유를 작성해야 합니다.
- 설치 단계를 확인하지 않습니다. 작동하지 않는 README는 신뢰를 파괴합니다.
- 코드를 반복하는 불필요한 주석입니다. 이는 소음을 발생시켜 실제 "이유" 해석을 모호하게 만듭니다.
- 대상 고객을 지정하지 않았습니다. 누구에게 작성되었는지 불분명한 문서는 초보자나 전문가 모두에게 아무 소용이 없습니다.
- 프로세스에서 업데이트를 분리합니다. 문서가 코드로 업데이트되지 않으면 빠르게 오해의 소지가 있습니다.
요약하면
AI는 빠른 초안 README, 독스트링, API 참조, 변경 로그 및 PR 설명 등 문서에서 기계적인 부담을 많이 덜어줍니다. 하지만 가장 가치 있는 레이어인 '왜'를 알 수 없고, 만들어내는 것은 위험하다. 노동 분업은 명확합니다. AI는 "무엇/어떻게"를 생성하고 "왜"를 추가합니다. 대상을 지정하고, 리소스를 제공하고, 구조를 부과하고, 적합한 장소를 표시하고, 직접 실행하여 각 설치 단계를 확인합니다. 문서를 코드 변경의 필수적인 부분으로 만드세요.
응용과제
문서가 누락되었거나 오래된 모듈이나 소규모 프로젝트를 선택하세요. 먼저 "구조화된 README 초안"(또는 문서 문자열) 템플릿을 사용하여 AI에서 개요를 생성합니다. 소스와 대상 청중을 제공하십시오. 그런 다음 AI가 [VERIFY] 또는 [WHY NEEDED]로 표시한 각 지점을 살펴보세요. 실제로 설정 단계를 실행하고 자신의 지식으로 디자인 "이유"를 입력하세요. 수정해야 할 단계 수와 추가한 "이유" 수를 확인하세요.
체크리스트
- [ ] 문서에서 나는 "무엇/어떻게"와 "왜" 레이어를 구분합니다.
- [ ] AI가 '이유'를 구성하도록 하는 것이 아니라 직접 추가합니다.
- [ ] 대상 고객과 실제 소스 파일을 프롬프트에 제공합니다.
- [ ] AI가 표시한 [VERIFY] 포인트를 직접 실행하여 검증합니다.
- [ ] 코드를 반복하는 불필요한 주석을 제거합니다.
- [ ] 코드 변경 중 문서 업데이트 부분을 만들고 있습니다.