작업 생성 및 코드 구현

Completed

기술 계획은 아키텍처 방향을 제공하지만 구현하려면 구체적이면서도 실행 가능한 단계가 필요합니다. 이 단원에서는 엔터프라이즈 시나리오에 대한 고급 작업 생성 및 관리 기술을 다룹니다.

작업 기본 사항 검토

GitHub Spec Kit의 /speckit.tasks 명령은 고급 아키텍처 결정을 tasks.md 파일의 특정 작업 항목으로 변환합니다. 각 작업은 독립적으로 구현, 테스트 및 확인할 수 있는 개별 작업 단위를 나타냅니다.

범위가 잘 지정된 작업의 주요 특징:

  • 실행 가능: 수행해야 할 작업을 명확하게 명시합니다.
  • 테스트 가능: 완료 확인은 간단합니다.
  • 독립: 관련 없는 작업을 기다리지 않고 완료할 수 있습니다.
  • 시간 제한: 적절한 기간(시간에서 하루)으로 완료할 수 있습니다.

단계 기반 조직

복잡한 기능은 작업을 단계로 구성하면 도움이 됩니다. 예를 들어 설치, 파운데이션, 핵심 기능, UI/통합, 보안 및 테스트가 있습니다. 각 단계는 중요 시점을 향해 빌드되는 논리적 그룹화를 나타냅니다.

작업 분석의 이점

작업 분석은 단순히 작업을 구성하는 것 이상의 여러 용도로 사용됩니다. AI가 단일 작업에서 전체 기능을 구현하려고 시도하지 않고 특정 목표에 대한 집중 코드를 생성하는 데 도움이 됩니다. 계속하기 전에 부분 구현을 테스트할 수 있는 자연 확인 지점을 만듭니다. 완료된 내용과 남은 내용을 정확하게 보여 줌으로써 정확한 진행률 추적을 가능하게 합니다. 종속성을 명시적으로 설정하여 팀 조정을 용이하게 합니다.

문서 업로드 기능의 경우 계획은 전체 아키텍처 및 기술 선택에 대해 설명합니다. 작업 목록은 아키텍처 결정을 특정 작업으로 변환합니다. 데이터베이스 테이블 만들기, API 엔드포인트 구현, React 구성 요소 빌드, 유효성 검사 논리 추가, 테스트 작성. 각 작업은 적절한 기간에 완료할 수 있을 만큼 작지만 의미 있는 진행률을 나타낼 수 있을 만큼 큽 수 있습니다.

작업 구조 및 조직 검사

잘 구성된 작업 목록은 작업을 논리적으로 구성하고 종속성을 적절하게 시퀀스하며 구현에 대한 명확한 지침을 제공합니다.

단계 기반 조직

복잡한 기능은 단계 기반 조직의 이점을 누릴 수 있습니다. 각 단계는 특정 중요 시점을 향해 빌드되는 관련 작업의 논리적 그룹화를 나타냅니다.

문서 업로드 기능의 경우 일반적인 단계 구조에는 다음이 포함될 수 있습니다.

  • 1단계: 기초 및 구성

    • appsettings.jsonAzure Blob Storage 연결 구성을 설정합니다.
    • 적절한 스키마를 사용하여 SQL 데이터베이스에서 DocumentMetadata 테이블을 만듭니다.
    • Azure.Storage.Blob NuGet 패키지를 백 엔드 프로젝트에 추가합니다.
    • 스토리지 작업을 캡슐화하는 DocumentService 클래스를 만듭니다.
  • 2단계: 핵심 업로드 기능

    • DocumentsController에서 POST /api/documents/upload 엔드포인트를 구현합니다.
    • DocumentService에 파일 유효성 검사 논리(크기, 형식)를 추가합니다.
    • 오류 처리를 사용하여 Blob Storage 업로드 메서드를 구현합니다.
    • 업로드에 성공한 후 데이터베이스에 문서 메타데이터를 저장합니다.
    • 문서 ID 및 URL을 사용하여 업로드 결과를 클라이언트에 반환합니다.
  • 3단계: 프런트 엔드 구현

    • 파일 입력을 사용하여 DocumentUpload React 구성 요소를 만듭니다.
    • 구성 요소에 파일 크기 및 형식 유효성 검사를 추가합니다.
    • 업로드 진행률 표시기를 구현합니다.
    • 업로드 성공 및 오류 응답을 처리합니다.
    • 업로드에 성공한 후 문서 목록을 새로 고칩니다.
  • 4단계: 보안 및 유효성 검사

    • 업로드 엔드포인트에 Microsoft Entra ID 인증 검사를 추가합니다.
    • 매직 번호를 사용하여 서버 쪽 파일 형식 유효성 검사를 구현합니다.
    • DoS 공격을 방지하는 요청 크기 제한을 추가합니다.
    • 허용된 목록에 대해 파일 확장의 유효성을 검사합니다.
    • 업로드 작업에 대한 감사 로깅을 추가합니다.
  • 5단계: 테스트 및 설명서

    • DocumentService 업로드 메서드에 대한 단위 테스트를 작성합니다.
    • 전체 업로드 흐름에 대한 통합 테스트를 만듭니다.
    • 오류 시나리오 테스트(잘못된 파일 형식, 크기 초과)를 추가합니다.
    • OpenAPI/Swagger의 문서 API 엔드포인트입니다.
    • 업로드 지침으로 사용자 설명서를 업데이트합니다.

이 단계적 접근 방식은 자연스러운 마일스톤을 만듭니다. 2단계가 끝나면 작동하지만 최소한의 기능만 갖춘 백엔드가 있습니다. 3단계 이후 사용자는 파일을 업로드할 수 있습니다. 4단계 이후 시스템은 안전하고 프로덕션 준비가 완료됩니다. 5단계 이후 모든 항목이 테스트되고 문서화됩니다.

작업 세분성 및 범위

각 작업의 범위는 적절하게 지정되어야 하며 명확한 방향을 제공할 수 있을 만큼 구체적이지만 규범적인 마이크로 관리가 될 정도로 상세하지는 않습니다.

범위가 잘 지정된 작업은 다음과 같은 특징을 공유합니다.

  • 실행 가능: 태스크는 수행해야 할 작업을 명확하게 설명합니다.
  • 테스트 가능: 작업이 완료된 시기를 확인할 수 있습니다.
  • 가능한 경우 독립적: 관련 없는 작업을 기다리지 않고 작업을 완료할 수 있습니다.
  • 시간 제한: 개발자는 적절한 기간(일반적으로 몇 주가 아닌 하루 시간)으로 작업을 완료할 수 있습니다.

범위가 잘 지정된 작업의 예: "다중 파트 파일 업로드를 수락하고, 파일 크기가 50MB 미만인지 확인하고, Azure Blob Storage에 파일을 저장하고, Blob URL 및 문서 ID를 반환하는 POST /api/documents/upload 엔드포인트를 구현합니다."

이 작업은 빌드할 대상(엔드포인트), 수락하는 항목(다중 파트 파일), 적용할 유효성 검사(크기 제한), 파일 저장 위치(Azure Blob Storage), 반환할 항목(URL 및 ID)에 대해 자세히 설명합니다. 개발자는 구현할 내용을 정확히 알고 있습니다.

다음은 범위가 부족한 작업의 예입니다. "업로드 작업 만들기" 이 예제에서는 "작업"의 의미 또는 관련된 구성 요소에 대한 실행 가능한 지침을 제공하지 않습니다.

다음은 지나치게 규범적인 작업의 예입니다. "DocumentsController.cs 줄 47에서 매개 변수(IFormFile 파일, 문자열 userId)를 사용하여 UploadDocument라는 메서드를 추가하고 정확히 다음 단계를 사용하여 구현합니다..." 이 작업 설명은 개발자 기관을 제거하고 코드 구조가 진화하는 것을 고려하지 않습니다.

작업 종속성 및 시퀀싱

작업 순서가 중요합니다. 일부 작업은 다른 작업을 시작하기 전에 완료해야 합니다.

백 엔드 코드는 스키마 존재 여부에 따라 달라지므로 일반적으로 데이터베이스 스키마 변경 내용이 먼저 표시됩니다. 백 엔드 API 엔드포인트는 해당 엔드포인트를 호출하는 프런트 엔드 구성 요소 앞에 옵니다. 구성 설정은 해당 구성을 사용하는 코드보다 먼저 이루어집니다. 테스트는 테스트 중인 코드가 있는 후에 수행됩니다.

작업 목록은 차단을 최소화하기 위해 시퀀스 작업을 수행해야 합니다. 프런트 엔드 및 백 엔드 작업이 독립적인 경우 병렬로 진행할 수 있습니다. 여러 백 엔드 엔드포인트가 있는 경우 개발자는 동시에 작업을 구현할 수 있습니다.

문서 업로드 기능의 경우 논리 시퀀스는 다음을 보장합니다.

  1. 구성 및 데이터베이스 설정이 먼저 수행됩니다(종속성 없음).
  2. 백 엔드 API 구현은 데이터베이스 설정을 따릅니다(스키마에 따라 다름).
  3. 프런트 엔드 구성 요소는 API 구현을 따릅니다(기존 엔드포인트에 따라 다름).
  4. 보안 강화는 핵심 기능(기존 코드에 따라 다름) 후에 발생합니다.
  5. 테스트는 모든 구현 후에 발생합니다(완료된 코드에 따라 다름).

이 작업 순서를 사용하면 관련 없는 작업이 완료될 때까지 기다리지 않고도 지속적인 진행이 가능합니다.

/speckit.tasks를 사용하여 작업 생성

GitHub 사양 키트는 GitHub Copilot 채팅의 /speckit.tasks 명령을 통해 작업 목록을 생성합니다. 이 명령은 spec.md 및 plan.md 모두 처리하여 포괄적인 정렬된 구현 작업 목록을 생성합니다.

AI는 사양을 분석하여 빌드해야 하는 사항을 이해하고, 아키텍처 접근 방식을 이해하기 위한 계획을 검토하고, 이러한 문서와 실제 코드 간의 격차를 해소하는 작업을 생성합니다. 결과 tasks.md 파일에는 번호 매기기 또는 글머리 기호 작업이 포함되어 있으며, 종종 복잡한 기능을 위한 단계로 구성됩니다.

작업 생성 명령 호출

Visual Studio Code에서 GitHub Copilot 채팅을 열고 /speckit.tasks을 입력합니다. GitHub Copilot는 사양을 처리하고 구조화된 작업 목록을 생성하도록 계획합니다. 생성 프로세스는 일반적으로 몇 분 후에 완료되어 구현 작업의 포괄적인 분석을 생성합니다.

작업 목록은 사양 및 계획에서 컨텍스트를 자동으로 상속합니다. 계획이 "Azure Blob Storage 사용"을 지정하는 경우 생성된 작업에는 Blob Storage 연결을 구성하고, 업로드 논리를 구현하고, 스토리지 오류를 처리하기 위한 특정 단계가 포함됩니다.

작업 목록 검토 및 유효성 검사

작업 목록은 완전성과 정확성을 보장하기 위해 중요한 검토가 필요합니다.

계획 요소의 적용 범위 확인

plan.md와 비교하여 tasks.md를 체계적으로 분석합니다. 계획의 모든 아키텍처 결정 및 구현 단계는 하나 이상의 작업에 해당해야 합니다.

계획에서 "서버 쪽 유효성 검사 구현"을 지정하는 경우 특정 태스크는 파일 형식 유효성 검사, 파일 크기 유효성 검사 및 오류 응답 처리를 처리해야 합니다. 계획에 "audit logging(감사 로깅)"이 언급되어 있으면 업로드 작업에 대한 로그 항목을 만들도록 작업에서 다뤄야 합니다.

누락된 작업은 불완전한 생성 또는 구체적인 작업으로 변환되지 않는 계획 요소를 나타냅니다. 작업을 수동으로 추가하거나 더 많은 컨텍스트를 제공하고 다시 생성하여 이 문제를 해결합니다.

논리적 간격 확인

계획에서 명확하지 않지만 구현 세부 정보를 고려할 때 명확하게 드러나는 기능 격차를 찾습니다.

일반적인 격차는 다음과 같습니다.

  • 오류 처리: 네트워크 오류, 스토리지 오류 또는 데이터베이스 문제를 처리하기 위한 작업이 있나요?
  • 에지 사례: 사용자가 이름이 동일한 파일을 업로드하면 어떻게 되나요? 동시 업로드는 어떻게 처리하나요?
  • 구성: 연결 문자열, API 키 및 서비스 엔드포인트가 제대로 구성되었나요?
  • 사용자 피드백: 업로드가 완료되거나 실패하는 경우 사용자는 어떻게 알 수 있나요?
  • 데이터 정리: 업로드가 부분적으로 성공하면 실패하고 정리가 처리되었나요?

검토 중에 이러한 간격을 식별하고 구현이 시작되기 전에 적절한 작업을 추가합니다.

작업 순서 및 종속성 평가

작업이 적절하게 시퀀스되는지 확인합니다. 데이터베이스 스키마 작업은 해당 테이블에 액세스하는 코드 앞에 있어야 합니다. API 엔드포인트 작업은 해당 엔드포인트를 호출하는 프런트 엔드 구성 요소보다 우선해야 합니다.

작업이 순서가 잘못되면 수동으로 순서를 다시 지정합니다. 예를 들어 프런트 엔드 작업이 해당 백 엔드 작업 앞에 나타나는 경우 해당 단계로 이동합니다.

동일한 단계 내의 태스크 간의 종속성을 고려합니다. 한 작업의 출력이 다른 작업에 필요한 경우 첫 번째 작업이 시퀀스 앞부분에 표시되는지 확인합니다.

작업 세분성 유효성 검사

각 작업의 범위가 적절하게 지정되었는지 확인합니다. 너무 큰 작업("전체 백 엔드 구현")은 더 작고 관리하기 쉬운 조각으로 세분화되어야 합니다. 너무 작은 작업("줄 42에 세미콜론 추가")을 더 의미 있는 단위로 결합해야 합니다.

범위가 잘 지정된 작업은 일반적으로 완료하는 데 몇 시간에서 하루가 걸리며 독립적으로 테스트할 수 있으며 입증 가능한 진행률을 생성합니다.

작업을 사용하여 구현을 안내하세요.

유효성이 검사되면 tasks.md 구현 로드맵이 됩니다.

체계적으로 작업을 진행

다음으로 이동하기 전에 각 작업을 완료하여 순서대로 작업을 수행합니다. 이 훈련된 접근 방식은 아무것도 건너뛰지 않도록 하고 명확한 진행률 지표를 제공합니다.

각 작업을 완료하면 다음을 수행합니다.

  1. 필요한 기능을 구현합니다.
  2. 구현을 테스트하여 정확성을 확인합니다.
  3. 작업을 완료로 표시합니다(확인란 또는 취소선 추가).
  4. 작업에 대한 참조를 사용하여 변경 내용을 커밋합니다.

이 체계적인 접근 방식은 완료된 작업을 특정 작업에 연결하는 명확한 감사 내역을 만듭니다.

진행 상황 추적 및 상태 전달

작업 목록은 진행률에 대한 객관적인 측정값을 제공합니다. 30개 작업 중 15개 작업이 완료되면 이 기능은 약 50개% 구현됩니다. 이 메트릭은 프로젝트 계획 및 관련자 통신에 도움이 됩니다.

팀과 tasks.md 공유하여 완료된 내용과 남은 내용을 전달합니다. 팀 구성원은 주의가 필요한 영역과 검토 노력에 집중할 위치를 한눈에 볼 수 있습니다.

구현 중 작업 조정

구현에 새로운 요구 사항 또는 더 나은 접근 방식이 표시되면 그에 따라 tasks.md 업데이트합니다. 작업 목록은 오래된 계획이 아니라 현실을 반영해야 합니다.

팀 구성원 간에 작업 배포

명확한 작업 정의는 여러 개발자 간에 작업을 분산할 수 있게 해줍니다. 백 엔드 팀은 프런트 엔드 팀이 UI 구성 요소를 빌드하는 동안 API 작업을 수행할 수 있습니다. 데이터베이스 관리자는 개발자가 구성을 준비하는 동안 스키마를 설정할 수 있습니다.

명시적으로 작업 종속성을 호출하면 차단을 방지하는 데 도움이 됩니다. 작업 B가 작업 A에 의존하는 경우 작업 A가 할당되고 적절한 우선 순위가 지정되었는지 확인합니다. 작업의 문서 완료 기준을 정립하여 핸드오프가 매끄럽게 이루어지도록 합니다.

/speckit.implement를 사용하여 코드 생성

이 /speckit.implement 명령은 tasks.md 사용하여 체계적으로 코드를 생성합니다. AI는 한 번의 패스로 전체 기능을 구현하는 대신 순차적으로 작업을 수행합니다. 이 방법은 보다 집중적인 올바른 코드를 생성합니다.

특정 작업 번호, 작업 범위 또는 tasks.md 파일에서 가져온 구현에 대한 설명을 사용하여 호출 /speckit.implement 할 수 있습니다. AI는 spec.md, plan.md 및 tasks.md 참조하여 전체 아키텍처 및 요구 사항에 맞는 코드를 생성합니다.

예를 들어 문서 업로드 엔드포인트를 구현하려면 다음을 입력할 수 있습니다.

/speckit.implement Implement the MVP first strategy (Tasks: T001 - T027)

이 명령은 AI가 T001~T027 작업에 집중하도록 지시하여 각 작업의 요구 사항을 순서대로 충족하는 코드를 생성합니다.

구현 중에 지원 제공

AI는 특정 작업을 진행하기 위해 지원 또는 권한이 필요할 수 있습니다. 예를 들어 작업에서 앱을 빌드하거나 실행해야 하는 경우 AI는 계속하기 전에 확인 메시지를 표시할 수 있습니다.

또한 AI는 작업의 구현을 테스트할 때 버그를 검색할 수 있습니다. 문제를 진단하는 데 도움이 되는 자세한 정보를 제공합니다. AI가 모호성을 발견할 경우 추가 컨텍스트 또는 설명을 제공할 수도 있습니다.

채팅 보기에서 지원을 요청하는 메시지가 표시되면 빠른 응답을 통해 구현이 원활하게 진행되는 데 도움이 됩니다.

확인 검사점

구현 명령을 완료한 후 계속하기 전에 결과를 확인합니다. 애플리케이션을 실행하고, 테스트를 실행하고, 각 태스크가 구현되고 해당 목표가 달성되고 있는지 확인합니다. 이 증분 확인은 가장 쉽게 해결할 수 있는 문제를 조기에 파악합니다.

작업 간 컨텍스트 유지 관리

작업을 진행하면서 이전에 완료된 작업은 후속 작업에 대한 컨텍스트를 제공합니다. AI는 관련 기능을 빌드하고, 코드 품질을 개선하고, 아키텍처 일관성을 유지할 때 이전 구현을 참조할 수 있습니다.

구현 작업을 관리할 때 일반적인 문제가 발생합니다.

범위가 확장되는 작업

구현 중에 태스크가 예기치 않은 복잡성을 표시하면 일시 중지하고 재평가합니다. 부풀어 오른 작업을 여러 작은 작업으로 분할합니다. 실제 범위를 반영하도록 tasks.md 업데이트합니다. 범위 확장을 관련자에게 전달합니다.

차단된 작업

경우에 따라 외부 종속성에 의해 작업이 차단됩니다. 차단된 작업을 tasks.md "BLOCKED: Azure Blob Storage 컨테이너 프로비저닝 대기 - 티켓 #1234"로 명시적으로 표시합니다. 차단된 작업을 별도로 추적하여 잊혀지지 않도록 합니다.

우선 순위 변경

비즈니스 요구 사항이 진화합니다. 우선 순위가 바뀌면 그에 따라 tasks.md 업데이트합니다. 새 우선 순위를 반영하는 방식으로 작업 순서를 다시 지정합니다. 새로운 요구 사항에 대한 새 작업을 추가합니다. 더 이상 유용하지 않은 작업을 지연하거나 제거하는 것이 좋습니다.

구현 중에 발견된 태스크 모호성

모호성이 표면화되면 구현을 일시 중지하고 설명을 구합니다. 사양을 검토하고 원래 의도를 이해하도록 계획합니다. 계속하기 전에 특정하고 명확한 언어로 작업 설명을 업데이트합니다.

요약

작업 생성은 아키텍처 계획을 실행 가능한 구현 단계로 변환합니다. 구현 작업의 구조적 단계 기반 분석을 만드는 데 사용하는 /speckit.tasks 작업 목록을 생성합니다. 생성된 작업을 중요하게 검토하여 포괄적인 검사, 논리적 시퀀싱 및 적절한 세분성을 확인합니다. 유효성이 검사된 작업 목록을 사용하여 체계적인 구현을 안내하고, 진행 상황을 추적하고, 팀 활동을 조정합니다.

spec.md, plan.md 및 tasks.md 조합하면 완전한 개발 프레임워크가 만들어집니다. 사양은 빌드할 내용과 이유를 정의합니다. 이 계획은 아키텍처적으로 빌드하는 방법을 정의합니다. 태스크는 빌드를 실행하는 특정 단계를 정의합니다. 이러한 아티팩트가 함께 모호한 요구 사항을 구현 전체에서 프로젝트 목표와 일치를 유지하는 구체적이면서 추적 가능한 개발 작업으로 변환합니다.