sd-manual

sd-manual

독자(주로 코드 작업 중인 에이전트)가 어떤 작업을 하려 할 때 그 작업을 올바르게 수행하는 방법을 빠르게 얻도록, 주제 단위 목적 기반 매뉴얼을 작성·갱신.

좋은 매뉴얼의 두 본질 축:

• 축1 — 작업 목적 단위로 조직: 독자는 "내가 무엇을 하려는지" 로 찾음. 매뉴얼은 "~하려면 ~한다" 구성이어야 하며, 구현 내부 동작을 설명 단위로 삼지 않음.
• 축2 — 방법이 실제 동작과 일치: 적은 방법이 코드의 실제 결과와 맞아야 함. 검증 기준은 독자가 관찰하는 최종 결과(화면·실제 동작)이며, 함수 내부 반환값이 아님.

산출물

• 활성 references 경로의 manuals/<주제>.md — 매뉴얼 본문.
• 활성 references 경로의 README.md 의 매뉴얼 인덱스 표 — 트리거 + 링크 1행.

워크플로

1. 대상·범위 확정

• 매뉴얼 주제와 대상 코드 범위 파악.
• 신규 작성인지, 기존 매뉴얼 갱신인지 판별. 갱신이면 기존 파일을 먼저 읽어 현재 구조를 파악.
• 독자가 이 매뉴얼로 하려는 작업들(use case)을 식별.

2. 작업 목적 분해 → 목차

• 1단계에서 식별한 작업들을 목차로 변환. 각 섹션 = 하나의 작업 목적("~하려면 ~한다").
• 함수·옵션을 나열하는 레퍼런스 구조나, 내부 동작을 설명하는 구조로 만들지 않음(축1).

3. 수행법 조사 + 결과 추적

• 각 작업의 수행법을 대상 코드를 직접 읽어 근거 위에 확정.
• 그 방법이 독자가 관찰하는 최종 결과(화면·실제 동작)로 이어지는지 끝까지 추적해 확인. 함수 반환값만 보고 결과를 단정하지 않음(축2).
• 갱신이면 코드 변경분이 어떤 작업 목적에 해당하는지 짚어 반영 위치를 정함.

4. 작성 + 인덱스 등재

• 기존 manuals/*.md 의 톤·구조를 답습: 목적 설명 → 작성법 + 코드 예시 → 지킬 것.
• 신규: README 매뉴얼 인덱스 표에 트리거 + 링크 1행 추가.
• 갱신: 기존 매뉴얼 파일과 인덱스 행을 보존한 채 변경분만 반영. 합의 없이 무관한 부분을 고치지 않음.

5. 자가 검증 게이트

출력 전 자문:

• 각 섹션이 작업 목적("~하려면") 단위인가, 구현 동작 설명이 아닌가?
• 각 서술이 독자가 관찰하는 최종 결과와 일치하는가(함수 반환값이 아니라)?
• 기존 매뉴얼의 톤·구조와 일관되는가?