Agents-On-Rails/skills

/aor-req — 요구사항 작성 (Requirements Authoring)

EARS-12 패턴, INCOSE C1-C9 품질 속성 및 표준 상호참조 구문에 따라 UN, PR, SR을 초안 작성합니다. 출력은 마크다운 형식입니다.

스킬과 에이전트에 관한 참고사항. AOR 번들에는 .claude/skills/aor-*/SKILL.md에 스킬이 포함되어 있으며(이 스킬처럼 직접 호출 가능), .claude/agents/aor-sme-*.md에 SME 에이전트가 포함되어 있습니다(하위 에이전트 시스템 프롬프트로, aor-review / aor-review-adhoc에 의해서만 호출됨). 에이전트를 스킬로 호출하지 마십시오 — "skill not found" 오류가 발생합니다.

운영 규율

전체 프로세스에 적용됩니다. 각 항목을 시작 시 명시하여 사용자가 확인할 수 있도록 합니다.

• 모드 (시작 시 선언): 탐색 세션(단일 요구사항, 대화형, 파일 없음)인지 문서 세션(전체 명세서 작성, 파일 저장)인지 질문합니다. 입력이 파일 경로 없이 인라인 텍스트로 제공되면 탐색 모드로 기본 설정하고, 그렇지 않으면 문서 모드로 설정합니다. 모드는 5-7단계가 디스크에 쓰기를 수행할지 여부를 제어합니다.
• 호출 확인: 스킬의 첫 번째 응답에서 "aor-req가 <모드> 모드로 실행 중입니다. 사용자가 요청하지 않는 한 파일은 <출력 경로>에 기록됩니다."라고 명시합니다. "스킬이 실제로 실행되었는가?" 모호성을 제거합니다.
• Q&A 규율: 한 번에 하나의 명확한 질문을 합니다. 사용자가 답변할 때까지 기다렸다가 다음 질문을 합니다. 질문을 쌓아두지 마십시오. 여러 대안을 제시하는 하나의 의사 결정(예: 다중 선택 메뉴)을 제시하는 단일 AskUserQuestion 호출은 하나의 질문입니다. 하나의 호출에서 두 개의 관련 없는 결정을 제시하는 것은 질문을 쌓는 것입니다.
• 실패 공개: 규정된 단계를 완료할 수 없는 경우(파일 쓰기 차단, 하위 에이전트 호출 실패, 참조 파일 사용 불가, 부분 완료, 시간 초과, 권한 거부) 채팅에 명시합니다. 공개 후 중단하고 재시도, 공개된 수동 에뮬레이션으로 대체, 또는 중단 중에서 선택하도록 질문합니다. 무시하고 계속 진행하지 마십시오. 명백히 일시적인 오류(예: 네트워크 시간 초과)의 경우 필수 공개 전에 한 번의 재시도가 허용됩니다.

워크플로우

1단계: 범위 설정

사용자가 범위 텍스트 또는 파일 경로를 전달한 경우 이를 사용합니다. 그렇지 않으면 AskUserQuestion을 통해 "어떤 기능이나 변경 사항을 명세해야 합니까?"라고 질문합니다.

범위 텍스트와 파일 경로 구별하기 (REQ-B): 입력이 다음 중 하나에 해당하면 경로로 처리합니다: (a) / 또는 \ 포함, (b) .md / .txt / .xlsx / .csv / .docx로 끝남, 또는 (c) Read()를 통해 디스크의 기존 파일로 확인됨. 그렇지 않으면 다중 단어 설명(예: "환자 예약 시스템")을 포함하여 범위 텍스트로 처리합니다.

동점 해결: 규칙 (c)만 일치하고(/ 또는 \ 없음, 인식된 확장자 없음, 그러나 Read()가 확인됨) 입력이 단일 단어인 경우, 경로로 처리하기 전에 사용자에게 확인합니다: "<input>이라는 파일이 존재합니다. 해당 파일을 의미한 것입니까, 아니면 범위 설명입니까?"

Excel 기반 입력의 경우, 이 스킬이 실행되기 전에 호스트 LLM이 행을 작업 마크다운 버퍼로 변환했을 것으로 예상합니다(번들은 Excel을 직접 구문 분석하지 않습니다).

1a단계: 수준 분류

탐색 모드인 경우 질문:

"이것은 User Need(UN), Product Requirement(PR) 또는 Software Requirement(SR)입니까?"

수준이 확인되면 사용되지 않는 단계를 건너뜁니다. UN 검토는 2단계가 필요합니다. PR 검토는 3단계 + 에코 게이트가 필요합니다. SR 검토는 4-6단계가 필요합니다.

탐색 모드의 다중 수준 입력: 사용자가 하나를 선택하는 대신 UN+PR+SR 세트(또는 여러 수준의 조합)를 제공하는 경우 다중 수준 검토로 처리합니다. 제공된 수준에 대해 순서대로 2-4단계를 진행하지만, 탐색 파일 쓰기 규율을 유지합니다(자동 디스크 쓰기 없음, 결과를 인라인으로 표시).

문서 모드인 경우, 사용자가 달리 지정하지 않는 한 기본적으로 2-4단계에 걸쳐 세 수준(UN → PR → SR)을 모두 진행합니다.

2단계: User Need 작성 (UN-NNN)

각 이해관계자 니즈에 대해 하나의 UN을 작성합니다. 규칙:

• 기술 중립적, 이해관계자 관점
• 일반적인 설명 (EARS 구문 아님)
• 문제 설명(2-3문장) + 니즈 설명 포함
• traces_to::UN->Persona [<persona-id>]를 통해 페르소나 태그 지정
• 우선순위: Critical | High | Medium | Low

형식은 templates.md를 참조하십시오.

3단계: Product Requirement 작성 (PR-NNN)

각 UN에 대해 PR을 도출합니다:

• 기술 중립적, 측정 가능, 객관적
• EARS 구문 (12가지 패턴은 ears-guide.md 참조)
• 각 PR은 역방향 추적: derived_from::PR->UN [UN-NNN]
• 각 PR은 순방향 추적: traces_to::PR->SR [SR-NNN]
• 모든 happy-path PR에는 최소 하나의 If/Then (Unwanted) PR 동반자가 있어야 함
• 동일한 If/Then 동반자 규칙이 4단계의 SR 수준에도 적용됨 — 모든 happy-path SR에는 구현 수준 복구를 지정하는 If/Then SR 동반자가 있어야 함
• 모든 EARS-N (부정/shall not) PR에는 예상되는 올바른 동작을 지정하는 최소 하나의 긍정 동반자 PR(Ubiquitous, Event-Driven 또는 State-Driven)이 있어야 함. 동일한 규칙이 SR 수준에도 적용됨

"Happy-path" 정의 (REQ-E): PR이 Ubiquitous, Event-Driven, State-Driven, Optional, Complex, EARS-E, EARS-T, EARS-P 중 하나의 긍정 EARS 패턴을 사용하는 경우 happy-path입니다. 제외: Unwanted Behaviour, EARS-N (부정/shall not), EARS-F (오류 모드 선언).

각 UN에 대해 적대적 오류 분해 (Adversarial Error Decomposition) 실행:

1. 어떻게 조용히 실패하는가?
2. 어떻게 시끄럽게 실패하는가?
3. 어떻게 부하 상태에서 실패하는가?
4. 어떻게 악의적인 상황에서 실패하는가?
5. 어떻게 시간이 지남에 따라 실패하는가?

각 오류 모드는 EARS If/Then PR이 되거나(제목에 [ADV] 태그, 식별자는 표준 유지, 예: PR-007 [ADV]), 별도 위험 등록부에 대한 참고 사항이 됩니다.

작업 예시. UN: "모든 업로드된 파일 보존". 오류 모드: "디스크 여유 공간이 부족할 때 조용히 실패". 결과 PR:

### PR-007 [ADV]: 디스크 압력이 높을 때 업로드 거부
디스크 여유 공간이 5% 미만으로 떨어지면 시스템은 HTTP 507 Insufficient Storage로 새 업로드를 거부하고 Retry-After 헤더를 반환해야 한다.
derived_from::PR->UN [UN-001]
traces_to::PR->SR [SR-014]

오류 모드가 구체적이고 정량화되었다는 점에 유의하십시오(5%, HTTP 507, Retry-After) — 이것이 PR을 검증 가능하게 만듭니다(C7).

4단계: Software Requirement 작성 (SR-NNN)

각 PR에 대해 SR을 도출합니다:

• 구현별: 서비스, API, 데이터베이스, 오류 코드 이름 지정
• 특정 구성 요소 이름을 가진 EARS 구문
• 각 SR은 역방향 추적: derived_from::SR->PR [PR-NNN]
• 각 SR은 순방향 추적: traces_to::SR->TC [TC-NNN]
• 절 수준 세분화(SR-NNN.c1, .c2)를 사용하여 관련 동작을 단일 SR ID로 통합
• 모든 happy-path SR에는 최소 하나의 If/Then (Unwanted) SR 동반자가 있어야 함 (happy-path 정의는 3단계 참조)
• 모든 EARS-N SR에는 최소 하나의 긍정 동반자 SR이 있어야 함

5단계: 필드 명세표

데이터 입력/표시 기능의 경우 SR 섹션에 필드 명세표를 추가합니다:

Field ID	Name	Label	Type	Min	Max	Unit	Default	Required	UI Exposure	Validation Rule	Error Msg	Parent SR

UI Exposure 값: editable | display-only | hidden.

6단계: 에코 게이트

각 SR 절에 대해 한 줄의 테스트 가능한 단언을 작성합니다:

VERIFY: [SR-NNN.c1] — [요구사항을 테스트 가능한 단언으로 다시 설명]

단언을 작성할 수 없는 경우 요구사항을 테스트할 수 없는 것입니다. 다시 작성하십시오.

7단계: 완전성 검사

작성이 완료되었다고 선언하기 전에 completeness.md의 체크리스트를 실행합니다.

대규모 입력 처리

입력이 약 200개 이상의 소스 항목(예: 대규모 Excel 붙여넣기)을 초과하는 경우:

1. 50행씩 배치로 분할합니다.
2. 각 배치에 대해: a. 배치를 읽습니다. b. 위 단계에 따라 마크다운 UN/PR/SR로 변환합니다. c. 작업 파일에 추가합니다 (덮어쓰지 않음). d. 진행 상황을 보고합니다: "개 중 번째 배치 완료; 개 요구사항 초안 작성됨."
3. 모든 배치 후 전체 파일에 대해 완전성 검사를 실행합니다.

배치에 모호한 입력이 포함된 경우 계속하기 전에 일시 중지하고 명확히 질문합니다. 행을 무시하고 넘어가지 마십시오.

출력 경로

기본값: 통합 UN/PR/SR에 대해 ./requirements/SPECIFICATION.md. 사용자가 재정의할 수 있습니다.

기존 파일을 업데이트하는 경우 기존 ID를 유지합니다. 다음 순차 번호로 새 ID를 추가합니다.

상호참조 구문 (치트 시트)

relation_type::SOURCE->TARGET [ID-list]

유형	방향	용도
traces_to	순방향	UN→PR, PR→SR, SR→TC, UN→Persona
derived_from	역방향	PR→UN, SR→PR, TC→SR
validates	검증	TC→SR
mitigates	위험 통제	SR→RISK
conflicts_with	모순	any→any

식별자 형식

정규식: ^(UN|PR|SR|TC)-\d{3}(\.[A-Z])?$

• 기본 ID: UN-001, PR-001, SR-001
• 하위 ID (EARS-P 표 형식): PR-010.A, PR-010.B
• 절 표기법: SR-001.c1, SR-001.c2

참조 파일

• ears-guide.md — 12가지 EARS 패턴
• templates.md — UN/PR/SR 섹션용 마크다운 템플릿
• completeness.md — 종료 체크리스트 (UN→PR→SR 커버리지)