Cue 배우기 · 작업 기반 튜토리얼

선택한 코드 변경 사항을 근거와 연동된 릴리스 노트로 변환하기

릴리스 노트는 다른 사용자가 직접 경험하게 될 변화에 대한 명확한 진술입니다. 커밋 메시지가 아닌, diff와 실제로 검증된 기록을 바탕으로 작성해야 합니다.

Cue 제품 팀 작성 · 2026년 9월 13일 업데이트. 실제 기록된 Cue 실행 결과가 아닌 가상 실습 자료입니다. 설치된 제어 기능 및 권한을 확인하세요.

핵심 요약

선택한 diff를 직접 확인하고 영향받는 대상별로 변경 사항을 분류한 후, 출처 참조와 함께 변경당 하나의 문장으로 작성하세요. Cue를 사용해 음성 설명을 캡처하거나 노트를 직접 입력한 다음 초안 작성을 요청하세요. 각 문장을 diff 및 테스트 기록과 대조해 확인하고, 추적할 수 없는 모든 주장은 삭제한 뒤 승인된 텍스트를 직접 게시하세요.

준비물: 편집 가능한 임시 메모 및 검토된 원본 자료(제공된 실습은 수동으로 진행 가능). 음성 입력을 사용할 경우 Cue Dictation을 구성하고 입력 상태를 먼저 확인하세요. 결과물: 각 줄마다 변경 사항과 근거가 명시된 릴리스 노트 초안 및 삭제하거나 단서를 달아야 할 주장 목록.

커밋 메시지 요약이 아닌, 뒷받침할 수 있는 문장을 작성하세요

선택한 코드 변경 사항을 명확히 뒷받침할 수 있는 릴리스 노트로 전환하려면: diff를 직접 읽고, 영향받는 대상별로 변경 사항을 묶고, 출처 참조와 함께 변경당 명확한 문장 하나를 작성하고, 실제로 검증된 기록을 첨부하며, 근거가 뒷받침되지 않는 모든 문장을 삭제하세요. diff를 보면서 Cue를 사용해 설명을 받아쓴 뒤, 검토된 텍스트를 바탕으로 초안을 요청할 수 있습니다. 이 텍스트 전용 실습은 저장소 접근, 테스트 실행, 태그 지정 또는 게시 권한을 부여하지 않습니다. 이는 작업 범위의 제한일 뿐, Cue나 연결된 Agent에 해당 기능이 없다는 의미는 아닙니다.

커밋 메시지는 작성자의 의도를 요약한 것일 뿐이며, 리뷰를 거친 후에는 불완전하거나 구식이 될 수 있습니다. 릴리스 노트는 이러한 주장을 코드를 볼 수 없는 사람들을 위한 기대로 전환합니다. 단일 출처를 전체 사용자 결과에 대한 증거로 취급하지 말고, diff, 테스트 및 배포 기록과 대조하여 대상을 검증하세요.

세 가지 경로를 사용할 수 있으며, 이는 순차적인 단계가 아니라 상황에 따른 대안입니다:

  1. 이미 사용 중인 도구에 직접 받아쓰기. 메모가 작성되고 있는 편집 가능한 필드, 임시 메모 또는 초안 파일에 포커스를 맞추고 Cue Dictation으로 설명을 음성 입력하세요. 입력된 텍스트를 검토하고 직접 제출하세요. Cue는 텍스트를 입력할 뿐이며, 문서는 텍스트를 받는 앱이 관리합니다.
  2. Cue 내에서 외부 Agent 선택. Agent 선택기가 있는 Cue 버전에서는 Claude 및 Codex가 로컬 Agent 선택지로 표시됩니다. Claude, Codex 또는 Gemini 같은 항목이 목록에 표시된다고 해서 연결, 로그인, 사용 가능한 모델 또는 저장소 접근 권한이 작동한다는 증거는 아닙니다. 어떤 정보를 전달하기 전에 해당 Agent가 접근할 수 있는 범위를 확인하세요.
  3. 지원되는 모델과 함께 Cue Agent 사용. Agent 열에서 Cue를 선택한 다음 사용 가능한 모델을 선택하세요. 이는 텍스트 초안을 작성하는 모델을 변경하는 것일 뿐, 터미널 접근, 저장소 체크아웃 또는 게시 권한을 부여하지는 않습니다.

변경 세트가 긴 경우, Cue의 녹음 및 전사 제어 기능을 사용하여 diff를 열어둔 상태에서 구두로 진행한 설명을 캡처할 수 있습니다. 해당 전사본은 검증된 기록이 아닌 원시 자료로 취급해야 합니다. 확인 단계는 녹음-컨텍스트 워크플로에서 다룹니다.

변경 세트, 검증된 기록 및 게시 대상 준비하기

이 워크플로는 사람이 릴리스 텍스트에 대한 책임을 진다고 가정합니다. 시작하기 전에 다음 네 가지를 준비하세요. 아래 실습 예제에 네 가지가 모두 제공되므로 저장소 없이도 과정을 따라 진행할 수 있습니다.

  • 정확한 변경 세트. 설명하려는 커밋 범위, 태그 또는 풀 리퀘스트와 해당 커밋 식별자. '지난주 작업 내용'은 변경 세트가 아닙니다. 범위를 명확히 규정할 수 없다면 어떤 변경 사항이 릴리스 노트에 포함되어야 하는지 구분할 수 없습니다.
  • diff 본문. 변경된 코드 줄과 이를 해석하기에 충분한 주변 코드. 커밋 제목 줄만으로는 코드가 실제로 무엇을 수행하는지에 대한 증거가 되지 못합니다.
  • 실제로 검증된 기록. 어떤 테스트가 존재하고 통과했는지, 어떤 플랫폼에서 실행되었는지, 어떤 부분이 다뤄지지 않았는지, 실제로 측정된 수치가 무엇인지 확인하세요. 측정된 것이 없다면 그것이 곧 기록이며, 추정치를 넣는 대신 언급하지 않는 것이 맞습니다.
  • 게시 대상 및 관련 규칙. 릴리스 노트가 게시될 위치, 승인권자, 팀 내 엠바고나 보안 공시 프로세스가 있는지 여부. 일부 수정 사항은 패치가 사용자에게 도달하기 전에 세부 정보를 공개해서는 안 됩니다.

Cue를 사용할 때는 설치된 버전의 제어 기능을 사용하고, Dictation을 위한 마이크 및 입력 권한을 확인한 뒤, 미완성 문장이 바로 게시된 릴리스 노트가 되지 않도록 임시 메모에서 시작하세요. 기본 단축키는 플랫폼마다 다르며 변경할 수 있습니다. 가이드에 언급된 키보다 사용 중인 프로그램의 설정이 우선합니다. 설정 및 입력 확인은 Dictation 튜토리얼을 참조하세요.

이 작업에서는 일반적인 문서 작성 작업보다 권한 관리가 훨씬 중요합니다. 비공개 diff는 외부 Agent와 공유하지 못할 수 있으며, 릴리스 노트는 조직의 제품 동작에 대한 약속이 될 수 있습니다. 최소한의 발췌문만 공유하고, 조직의 데이터 처리 규칙을 준수하며, 기밀 정보를 제공하기 전에 Cue의 개인정보 처리방침을 검토하세요.

실습: 가상 메모 앱의 1.4.0 릴리스

아래의 모든 내용은 'Example Notes'라는 가상 앱을 위한 실습용 자료입니다. 커밋과 테스트 기록은 실습을 위해 만들어진 것이며 코드는 불완전한 발췌본입니다. 여기에 포함된 내용은 Cue 제품의 동작, 기록된 Cue 실행 결과, 또는 측정된 결과가 아닙니다. 저장소나 Agent 계정 없이도 원본 자료를 수동으로 검토할 수 있습니다. 네 개의 원본 자료를 빈 메모에 복사하세요. 이 실습에서는 소비자가 src/index.mjs에서 다시 내보낸 함수를 가져온다고 가정하며, 다른 호환성 내보내기는 제공되지 않습니다.

코드, 식별자 및 확인 대상 문장의 일관성을 유지하기 위해 네 개의 원본 블록은 모든 언어 버전에서 영어 원문 그대로 유지됩니다. 설명과 풀이 답변은 별도로 번역됩니다. 이 불완전한 diff를 프로그램으로 실행하지 마세요.

C-01 — 선택한 변경 세트(가상 커밋 5개):

a1b2c3d  feat(export): include the note title in the exported file name
e4f5a6b  refactor(export): extract buildExportName from the export handler
9c0d1e2  fix(export): stop trimming the final page when a note ends with an empty block
7f8a9b0  chore(deps): update markdown-render 2.3.1 -> 2.4.0
3d4e5f6  feat(sync): add background sync retry behind the disabled syncRetry flag

C-02 — 위 커밋들의 diff(통합 표시):

--- a/src/export-name.mjs
+++ b/src/export-name.mjs
@@
-export function exportName(note) {
-  return `note-${note.id}.pdf`;
-}
+const MAX_TITLE = 40;
+
+export function buildExportName(note) {
+  const title = (note.title || '').trim().slice(0, MAX_TITLE);
+  const safe = title.replace(/[^\p{L}\p{N} _-]/gu, '').trim();
+  return safe ? `${safe}.pdf` : `note-${note.id}.pdf`;
+}

--- a/src/index.mjs
+++ b/src/index.mjs
@@
-export { exportName } from './export-name.mjs';
+export { buildExportName } from './export-name.mjs';

--- a/src/export-pages.mjs
+++ b/src/export-pages.mjs
@@
 export function exportPages(blocks) {
-  return paginate(blocks.filter(block => block.text.length > 0));
+  return paginate(blocks);
 }

--- a/package.json
+++ b/package.json
@@
-    "markdown-render": "2.3.1"
+    "markdown-render": "2.4.0"

--- a/src/sync.mjs
+++ b/src/sync.mjs
@@
 export function scheduleSync(config, queue) {
+  if (config.syncRetry) return scheduleWithRetry(queue, { attempts: 3 });
   return scheduleOnce(queue);
 }

C-03 — 이번 릴리스에서 실제로 검증된 기록:

Unit tests for export-name.mjs: 6 cases pass. Covered: usable title, empty title,
title of only punctuation, title over 40 characters, missing title property,
non-Latin title.
export-pages.mjs: no test covers this file, before or after the change.
Manual export: run on macOS only. Not run on Windows.
markdown-render 2.4.0: upstream release notes were not read. Reason for the bump
is recorded only as "routine update".
config/defaults.json: syncRetry is false. Not changed in this release.
Performance: no measurement was taken before or after these changes.
Crash reports: none were linked to any commit in this change set.

C-04 — 검증이 필요한 동료의 릴리스 초안 문장:

1. Exports are now named after your note.
2. Fixed a crash that caused the last page to disappear.
3. Export is about twice as fast.
4. Background sync retry is now available.
5. Internal refactor only, no API changes.
6. Updated markdown-render for security.

위의 diff는 가독성을 위해 하나의 블록으로 표시되었습니다. 이는 각 줄을 어떤 커밋이 도입했는지 증명하지 않습니다. 실습 답변에는 C-02와 파일 경로를 인용하고, C-01의 제목은 검증해야 할 주장으로만 취급하세요. 실제 작업에서는 문장에 커밋 식별자를 연결하기 전에 각 커밋의 개별 diff를 확인해야 합니다.

C-04보다 C-02를 먼저 읽으세요. 각 문장마다 필요한 수정 사항이 다릅니다. 소스 동작, 테스트 적용 범위 및 실제 제공 여부는 서로 별개의 문제입니다. 이름이 바뀐 함수는 이 픽스처의 공개 진입점에서 다시 내보내집니다. 필터 호출을 제거하면 모든 블록이 paginate로 전달되지만 해당 구현이 누락되어 있어 최종 PDF 레이아웃이나 충돌 수정 여부를 확인할 수 없습니다. 기본값이 꺼져 있는 플래그는 다른 곳에서 활성화할 수 있는지 여부를 알려주지 않습니다. 또한 JavaScript의 slice(0, 40)은 표시되는 문자 수가 아니라 UTF-16 코드 단위를 계산합니다.

설명 캡처 및 제한된 범위의 초안 요청하기

  1. diff와 빈 임시 메모를 나란히 여세요. 게시 도구의 릴리스 설명 입력란에서 바로 시작하지 마세요.
  2. 메모의 텍스트 필드에 포커스를 두고, Cue 설정에 표시된 단축키로 Dictation을 시작한 후, 말하기 전에 녹음 상태를 확인하세요. 캡처 기능을 사용할 수 없다면 음성 대신 직접 타이핑하세요. 이 실습은 오디오 기능에 의존하지 않습니다. 더 긴 녹음의 경우, 연결된 녹음-컨텍스트 가이드의 설정 및 검토 확인 단계를 먼저 따르세요.
  3. 변경 사항을 하나씩 소리 내어 설명하세요. 각 변경 사항마다 코드가 현재 수행하는 작업, 이를 체감할 대상, 본인이 직접 확인한 사항을 말하세요. 확인하지 않은 항목에 대해서는 '확인되지 않음'이라고 말하세요. 이 표현은 나중에 다시 기억해내는 것보다 기록해두는 편이 훨씬 명확합니다.
  4. 받아쓰기를 중지하고 처리가 끝날 때까지 기다린 후 입력된 텍스트를 읽으세요. 커밋 식별자, 파일 경로, 버전 번호 및 플래그 이름은 말로 전달하기보다 원본에서 복사해 붙여넣으세요. 음성은 전반적인 설명에는 적합하지만 9c0d1e2와 같은 식별자에는 정확도가 떨어집니다.
  5. 작성한 메모 옆에 원본 자료를 모아두세요. 수정한 텍스트가 이미 명확하다면 Agent를 건너뛰고 직접 편집하세요. 구조화와 문장 표현에 도움이 필요하다면 Cue Agent 또는 연결된 외부 Agent를 열고 C-01부터 C-04까지 명시적으로 붙여넣으세요. 저장소 창이 열려 있다고 해서 Agent가 해당 컨텍스트를 전달받은 것은 아닙니다.
  6. 초안 작성 요청을 전송하세요. 근거 없는 문장이 매끄러운 단락 속에 슬그머니 묻히지 않도록, 릴리스 노트, 근거 표, 주장 검증을 세 개의 개별 블록으로 나누어 요청하세요.
  7. 검증 절차를 거쳐 C-02 및 C-03과 대조하여 초안을 직접 검토하세요. 그런 다음 승인된 텍스트를 릴리스 도구에 복사하고, 편집 중인 버전과 대상을 확인한 후 직접 게시하세요. 어떤 Agent에게도 태그 지정, 푸시, 배포 또는 메모 게시를 요청하지 마세요.

릴리스 노트 요청 프롬프트 복사

대괄호 안의 필드를 검토 완료된 실제 원본 자료로 바꾸거나, C-01부터 C-04까지 붙여넣어 연습하세요. 실제 작업에서는 자리표시자를 남겨두지 마세요.

작업: 제공된 원본 자료만을 바탕으로 릴리스 노트를 작성하세요. 어떤 것도 직접 게시하지 마세요.
릴리스: [버전 및 플랫폼]
원본 자료:
C-01 커밋 목록, C-02 diff, C-03 검증 기록,
C-04 타인이 작성한 초안 문장.

세 개의 개별 블록으로 결과를 작성하세요.

블록 A. 릴리스 노트 (다음과 같이 그룹화):
- 사용자 변경 사항
- 이 패키지를 임포트하는 사용자를 위한 변경 사항 (공개 인터페이스가 변경된 경우에만)
- 내부 및 의존성 변경 사항
- 기본적으로 비활성화되어 있거나 제공 여부가 아직 검증되지 않은 항목
- 측정되지 않은 항목
각 변경 사항을 명확하고 쉬운 언어로 문장당 하나씩 작성하세요. 코드와 인터페이스에 대한 문장은 C-02와 파일 경로를, 검증·측정·기본 설정에 대한 문장은 C-03을 인용하세요. 통합 diff는 개별 코드 줄을 커밋에 직접 매핑하지 않으므로, C-01의 제목을 바탕으로 이러한 매핑을 유추하지 마세요. 대체 동작, 자르기 처리, 기본값, 테스트되지 않은 파일 등 원본 자료에 나타난 조건과 한계를 명시하세요.

블록 B. 근거 표: 문장, 해당 코드 줄 또는 C-03 항목, 아직 검증되지 않은 사항. 소스 코드가 뒷받침하는 동작과 테스트를 거친 동작을 구분하세요. 테스트 누락은 테스트되지 않았음을 의미할 뿐 자동으로 거짓임을 뜻하지는 않으며, 발췌문으로 입증되지 않은 결과는 미검증 상태로 남겨두어야 합니다.

블록 C. 각 C-04 문장에 대한 검증: 뒷받침됨, 불완전함, 근거 없음, 상충됨 중 하나로 판정하고 이유를 제시하며, 가능한 경우 근거가 허용하는 표현을 작성하세요. 완전히 삭제해야 하는 모든 문장을 별도로 나열하세요.

규칙:
제공된 원본 자료만 사용하세요. 원인, 충돌, 사용자 수, 속도 변화, 보안 영향, 고객 불만을 임의로 유추하지 마세요.
커밋 메시지는 주장일 뿐 근거가 아닙니다. diff와 상충하는 경우 diff를 따르고 충돌 사실을 표시하세요.
기본값이 비활성화 상태라는 것이 완전히 사용할 수 없다는 증거는 아닙니다. 문서화된 기본값만 보고하고, 옵트인 경로, 출시 상태 또는 전면적인 사용자 제공 여부를 임의로 단정하지 마세요.
C-03에 기록되지 않은 테스트를 설명에 포함하지 마세요.
초안 작성만 수행하세요. 태그 지정, 릴리스, 게시, 푸시, 배포, 파일 편집을 수행하지 마세요.

예시 출력

아래의 세 블록은 이 실습을 위해 작성된 예시입니다. 이는 기록된 Cue 실행 결과가 아니며 제품 출력 샘플이나 Agent의 답변에 대한 보증이 아닙니다. 직접 도출한 결과와 비교해 보세요.

예시 릴리스 노트:

Example Notes 1.4.0 (가상 실습 릴리스)

사용자 변경 사항
- 내보내기 파일명에 공백이 제거된 제목의 처음 40개 UTF-16 코드 단위를 사용한 후 지원되지 않는 문자를 제거합니다. 남는 문자가 없으면 파일명은 note-{id}.pdf가 됩니다. 제공된 테스트 기록에는 6개의 통과 사례가 나열되어 있으나 실제 테스트 코드는 제공되지 않았습니다. (C-02: src/export-name.mjs; C-03)
- 빈 텍스트 블록을 걸러내지 않고 모든 블록이 paginate로 전달됩니다. paginate 구현이 제공되지 않았고 C-03에 이 파일에 대한 테스트가 기록되지 않았으므로 최종 PDF 레이아웃 및 충돌 해결 여부는 확인되지 않았습니다. (C-02: src/export-pages.mjs; C-03)

이 패키지를 임포트하는 사용자를 위한 변경 사항
- 패키지 인덱스에서 내보낸 함수 이름이 exportName에서 buildExportName으로 변경되었습니다. 이번 실습의 공개 진입점 가정에 따라 exportName을 가져오는 코드는 업데이트가 필요합니다. (C-02: src/index.mjs)

내부 및 의존성 변경 사항
- markdown-render가 2.3.1에서 2.4.0으로 업데이트되었습니다. 업스트림 릴리스 노트를 검토하지 않았으므로 그 영향과 보안상 중요성은 확인되지 않았습니다. (C-02: package.json; C-03)

기본적으로 비활성화된 항목
- 재시도 로직이 존재하지만 제공된 기본값 설정에서 syncRetry는 false로 유지됩니다. 옵트인 가능 여부 및 배포 상태는 제공되지 않았습니다. (C-02: src/sync.mjs; C-03)

측정되지 않은 항목
- 이번 릴리스에 대해 성능 측정이 수행되지 않았습니다. (C-03)
- 이 변경 세트의 어떤 커밋에도 충돌 보고서가 연결되지 않았습니다. (C-03)
- 내보내기 수동 테스트는 macOS에서만 실행되었습니다. (C-03)

예시 근거 표 (블록 B):

문장 제공된 코드 또는 기록 미검증 상태로 남은 내용
내보내기 파일명 명명 규칙 및 대체 동작 C-02, src/export-name.mjs: .trim().slice(0, MAX_TITLE), 치환 정규식, safe ? ... : ...; C-03에 6개 통과 사례 기록 테스트 원본 코드 및 실행 결과가 제공되지 않음(실제 Cue 실행이 아닌 가상 기록임)
빈 텍스트 블록이 페이지네이션으로 전달됨 C-02, src/export-pages.mjs: return paginate(blocks);; C-03에 해당 파일에 대한 테스트 기록 없음 최종 PDF 레이아웃 및 충돌 발생 동작(paginate 구현 누락)
공개 함수 이름 변경 C-02, src/index.mjs: 내보내기 exportName이 buildExportName으로 변경됨 다운스트림 호출자 및 마이그레이션 결과(공개 진입점 역할은 명시적인 실습 가정임)
의존성 버전 변경 C-02, package.json: 2.3.1이 2.4.0으로 변경됨; C-03에는 일상적인 업데이트(routine update)로만 기록 보안상의 중요성 및 업스트림 동작(업스트림 릴리스 노트를 검토하지 않음)
재시도 분기, 기본값 꺼짐 C-02, src/sync.mjs: if (config.syncRetry); C-03에 syncRetry는 false로 명시 옵트인 접근성, 롤아웃 및 배포 상태
성능 측정 및 연결된 충돌 보고서 없음, macOS에서만 수동 내보내기 실행 C-03의 측정 항목, 충돌 보고서 항목 및 수동 확인 항목 성능 수치, 충돌 해결 여부 및 기타 플랫폼에서의 동작

예시 주장 검증, C-04 체크리스트:

# C-04 초안 문장 판정 및 이유 근거가 허용하는 표현
1 "Exports are now named after your note." 불완전함. 대체 동작, 필터링 처리, 필터링 전 처음 40개 UTF-16 코드 단위 자르기 내용이 누락되었습니다. 내보내기 파일명 함수와 해당 조건을 설명하되, 화면에 표시되는 40자라고 보장하지 마세요.
2 "Fixed a crash that caused the last page to disappear." 확인되지 않음. 충돌 보고서, export-pages 테스트, paginate 구현이 제공되지 않았습니다. "빈 텍스트 블록을 필터링하지 않고 모든 블록이 paginate로 전달됩니다. 최종 PDF 동작은 확인되지 않았습니다."
3 "Export is about twice as fast." C-03에 어떤 측정 기록도 존재하지 않습니다. 삭제하세요. 원본 자료 중 속도 관련 내용을 뒷받침하는 근거는 없습니다.
4 "Background sync retry is now available." 실제 제공 여부가 확인되지 않았습니다. false 기본값과 조건부 코드 분기만 제공됩니다. "기본적으로 활성화되지 않음. 옵트인 및 롤아웃 상태는 확인되지 않았습니다."
5 "Internal refactor only, no API changes." src/index.mjs와 모순됩니다. 공개 내보내기 함수 이름이 변경되었습니다. 이름 변경 사실과 이것이 패키지 사용자에게 미치는 영향으로 대체하세요.
6 "Updated markdown-render for security." 업데이트 이유가 확인되지 않았습니다. C-03에는 'routine update'로만 기록되어 있습니다. "markdown-render를 2.3.1에서 2.4.0으로 업데이트했습니다. 업스트림 릴리스 노트는 검토되지 않았습니다."

5번 문장은 특히 주의 깊게 살펴볼 필요가 있습니다. '내부적'이라는 말은 파일 자체가 아니라 대상 고객에 대한 주장입니다. 모듈 내부에서의 이름 변경은 내부적이지만, 패키지 인덱스에서의 동일한 이름 변경은 해당 패키지를 가져오는 모든 사용자에게 중대한 호환성 파괴 변경 사항(breaking change)이 됩니다.

diff와 대조하여 모든 문장 검증하기

초안을 한쪽에 두고 다른 한쪽에는 C-02와 C-03을 띄운 상태에서 직접 이 검증 단계를 수행하세요. 릴리스 노트를 작성한 동일한 Agent에게 내용이 정확한지 확인해 달라고 요청하지 마세요.

확인 항목 통과 기준 반려 기준
추적 가능성 코드 및 인터페이스 관련 문장에 C-02와 파일 경로가 명시되어 있고, 검증, 측정 및 기본 설정 문장에 C-03이 인용되어 있음. 실제 커밋 기여 표기는 커밋별 diff가 필요함 선택한 변경 세트 외부의 작업을 설명하는 문장이 있거나, 제목만 보고 커밋 출처를 임의로 추정한 경우
근거 기반 여부 동작 설명 문장이 C-02의 코드를 가리키고, 검증 범위 설명 문장이 해당 C-03 기록을 명시함 커밋 메시지만으로 뒷받침되는 문장이 있거나, 소스 코드 확인 내용을 실행된 테스트인 것처럼 표현한 경우
대상 청중 적합성 일반 사용자에게 노출되는 변경, 임포트하는 개발자에게 노출되는 변경, 내부 변경 사항이 별도 섹션으로 구분되어 있음 공개 인터페이스 변경 사항을 '내부 변경'으로 분류한 경우
조건 명시 여부 대체 동작, 한계, 테스트되지 않은 파일, 기본 꺼짐 플래그가 명시되어 있음 코드에서 보장하지 않는 무조건적인 약속을 기재한 경우
측정 여부 C-03에 측정 기록이 없는 항목에 대해 침묵을 유지함 속도, 정확도, 신뢰성 또는 절약된 시간에 대한 임의의 수치를 적은 경우
출처 왜곡 없음 원인, 충돌 또는 고객 사례를 임의로 지어내지 않음 연결된 보고서가 없음에도 '사용자가 보고한 충돌 수정'이라고 작성한 경우
정직한 범위 설정 플랫폼 및 테스트 적용 범위가 C-03과 일치함 한쪽 플랫폼에서만 실행되었음에도 'macOS 및 Windows에서 테스트됨'이라고 표기한 경우

역방향 읽기로 검증을 마무리하세요. C-01과 C-04를 가리고 diff와 C-03만 읽은 뒤 처음부터 쓴다면 무엇을 적을지 자문해 보세요. 남아 있는 모든 주장에는 출처가 필요하며, 근거 없는 문장이 어디서 비롯되었는지 임의로 추측하지 마세요. 나중에 기록이 변경되는 경우(예: 누군가 export-pages.mjs에 대한 테스트를 추가함), 문장과 근거를 함께 업데이트하세요.

이 방법이 적합하지 않은 경우

  • 이 실습은 텍스트 전용이며 초안 작성만을 위한 것입니다. 검토된 원본 자료를 명시적으로 제공하세요. 이 실습을 위해 파일 변경, 테스트, 네트워크 요청, 태그 지정 또는 게시 권한을 부여하지 마세요. 실제 도구 지원 여부는 설치된 버전, 선택한 Agent, 연결 및 권한에 따라 달라지며 이 문서에서 단정하지 않습니다.
  • 규모가 크거나 squash된 릴리스는 한 번의 검토 작업 범위를 벗어납니다. 이 방법은 처음부터 끝까지 직접 읽을 수 있는 크기의 변경 세트에 적합합니다. 수백 개의 커밋은 사전 분류가 필요하며, 무관한 변경 사항들이 묶인 스쿼시 커밋은 신뢰하기 어려운 참조가 되므로 커밋 대신 파일이나 범위를 가리키고 그 사실을 명시해야 합니다.
  • 비공개 코드는 작업 환경 밖으로 유출되어서는 안 됩니다. 승인 없이 고용주나 고객의 diff를 외부 Agent에 붙여넣지 마세요. 의문이 든다면 임시 메모에서 직접 초안을 작성하고 Agent 단계를 건너뛰세요.
  • 보안 수정 사항은 별도의 프로세스를 따릅니다. 패치가 사용자에게 도달하기 전에 취약점을 설명하는 것은 보안 위험을 초래할 수 있습니다. 조직의 보안 공개 규칙이 이 문서의 모든 문구 제안보다 우선합니다.
  • 코드가 병합(shipped)되었다고 해서 바로 사용자에게 제공(available)되는 것은 아닙니다. 기능 플래그, 단계적 롤아웃, 서버 측 게이트, 앱 스토어 심사 등이 병합된 커밋과 실제 사용자 사이에 존재합니다. diff만으로는 어떤 조건이 적용되는지 알 수 없습니다.
  • 릴리스 노트는 품질을 인증하는 보증서가 아닙니다. 단지 변경 사항을 설명할 뿐입니다. 릴리스가 올바르거나 안전하거나 완전하다는 증거가 되지 않습니다.
  • 다른 언어로의 번역은 별도의 검토 과정입니다. 번역된 릴리스 노트는 그 자체로 새로운 진술들의 집합입니다. 영문 버전을 확인했다고 해서 번역본까지 검증된 것은 아닙니다.

초안이나 기록에 오류가 있을 때 대처 방법

초안의 문장을 어떤 변경 사항과도 연결할 수 없는 경우

해당 문장을 먼저 삭제한 후 근거를 찾으세요. 변경 사항이 실제 존재하지만 C-01에서 누락된 것이라면 변경 세트 범위 설정이 잘못된 것이므로 범위를 수정한 뒤 다시 초안을 작성하세요. 근거가 전혀 존재하지 않는다면 그것은 실제 변경이 아니라 단순한 주장에 불과합니다.

커밋 메시지와 diff가 일치하지 않는 경우

diff를 따르고 코드가 수행하는 작업을 설명하세요. 상충 내용을 기록하고 작성자에게 문의하세요. 오해의 소지가 있는 커밋 메시지는 대개 변경 사항이 의도보다 많거나 적게 반영되었음을 의미하기 때문입니다. 코드 내용보다 커밋 메시지를 우선시하여 릴리스 노트를 게시하지 마세요.

Agent가 원본 자료에 없는 파일이나 커밋을 인용하는 경우

해당 줄만 고치려 하지 말고 응답 블록 전체를 거부하세요. 원본 자료를 다시 제공하고, 제공된 diff 코드 줄만 인용하는 문장을 요청한 뒤 결과를 다시 확인하세요. 한 섹션에서 지어낸 참조가 발견되었다면 해당 응답의 나머지 내용도 신뢰하기 어렵습니다.

Dictation이 버전 번호나 커밋 해시를 잘못 인식한 경우

텍스트를 사용하기 전에 직접 수정하고, 원본에서 값을 복사하여 붙여넣으세요. 잘못된 식별자가 이미 초안에 들어갔다면 문서 전체를 검색하여 모든 사본을 수정하세요. 식별자는 반복 사용되는 경향이 있기 때문입니다. Agent가 대신 태그 지정, 푸시 또는 게시를 제안하더라도 거절하고 릴리스 단계를 직접 완료하세요.

뒷받침되지 않는 주장이 포함된 채 릴리스 노트가 이미 게시된 경우

팀의 정규 프로세스에 따라 게시된 텍스트를 수정하고, 변경된 내용과 시점을 명시하세요. 숫자를 몰래 수정해서는 안 됩니다. 해당 주장이 동작에 대한 약속이었다면, 정정 내용을 얼마나 공개적으로 알려야 할지 결정하기 전에 사용자가 이를 바탕으로 조치를 취했는지 확인하세요.

Cue의 캡처 또는 텍스트 입력 문제가 발생하는 경우 플랫폼, Cue 버전, 실행 모드 및 비식별화된 예시를 포함하여 Cue 지원팀에 문의하세요. 비공개 저장소, 자격 증명 또는 공개되지 않은 보안 세부 정보를 전송하지 마세요.

이 실습과 관련해 자주 묻는 질문

이 실습을 진행하려면 Git 저장소가 필요한가요? 아닙니다. C-01부터 C-04까지 완벽하게 제공됩니다. 텍스트 전용 실습이며 실제 제품의 실제 코드가 아니므로 어떤 Agent에 붙여넣어도 안전합니다.

Cue가 diff를 자동으로 가져올 수 있나요? 그렇게 가정하지 마세요. 설치된 버전과 선택한 Agent가 실제로 접근할 수 있는 권한을 확인하고, 신뢰하기 전에 검증하세요. 이 워크플로에서는 사용자가 diff를 텍스트로 직접 제공하므로 코드를 직접 읽게 되는 효과도 있습니다.

내부 리팩터링 내용을 릴리스 노트에 포함해야 하나요? 대개 별도 섹션에 기재하거나 전혀 포함하지 않습니다. 기준은 변경 규모가 작은지가 아니라, 패키지를 가져오는 개발자를 포함하여 팀 외부의 누군가가 그 변화를 감지할 수 있는지 여부입니다.

'사용자에게 노출되는 변경 사항 없음'이라고 작성해도 안전한가요? 공개 인터페이스, 출력 형식, 오류 메시지, 기본값, 의존성을 모두 확인한 후에만 가능합니다. 실습의 5번 문장이 바로 이 검증을 통과하지 못하는 사례입니다.

출처 및 관련 워크플로

이 튜토리얼은 가이드용으로 문서화된 Cue의 Dictation 및 Agent 기능 범위를 설명합니다. Git, CI, 패키지 레지스트리 또는 릴리스 도구와의 연동을 주장하지 않습니다. 가상의 실습보다 사용자 환경에 설치된 제어 기능과 조직의 릴리스 프로세스가 우선합니다.