spr-ai-native 0.4.0 → 0.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md
CHANGED
|
@@ -227,7 +227,7 @@ works/<task_id>/
|
|
|
227
227
|
|
|
228
228
|
- **PM은 서브에이전트가 아니라 메인 세션의 역할**입니다. `/pm`으로 진입하면 그 세션이 PM이 되어 나머지 3개에게 위임합니다. 서브에이전트가 다시 서브에이전트를 호출하는 중첩 위임에 의존하지 않으므로 세 도구에서 동일하게 동작합니다. 다만 도구 권한으로 PM의 코드 수정을 차단할 수 없어 프롬프트 규율에만 의존합니다 — 중첩 위임 의존성을 없애기 위한 트레이드오프입니다.
|
|
229
229
|
- **task_id는 사용자에게 확인받습니다.** PM이 git 브랜치명에서 후보를 제안하지만 확정은 사용자가 합니다. 디렉터리명이 되므로 `/`나 공백이 들어가면 되묻습니다.
|
|
230
|
-
-
|
|
230
|
+
- **engineer fix 재호출은 최대 3회**입니다 (engineer 호출 최대 4회, qa 호출 최대 4회). 3회 fix 후에도 FAIL이면 임의로 통과시키지 않고, `pm-report.md`에 `판정: 미완료(에스컬레이션)`으로 기록한 뒤 사용자에게 넘깁니다. fix 루프 없이 검증만 받고 싶으면 `/engineer` → `/qa`를 쓰세요.
|
|
231
231
|
|
|
232
232
|
### 어느 진입점을 쓸까
|
|
233
233
|
|
|
@@ -249,19 +249,6 @@ works/<task_id>/
|
|
|
249
249
|
|
|
250
250
|
개별 커맨드는 해당 서브에이전트만 호출하는 얇은 래퍼입니다. 브리프 게이트도, QA fix 루프도 없습니다 — QA가 FAIL이면 fix를 제안만 하고 재호출은 직접 하셔야 합니다. 산출물 파일 규약은 `/pm`과 동일하므로, 개별 커맨드로 시작했다가 도중에 `/pm`으로 넘어가도 이어집니다.
|
|
251
251
|
|
|
252
|
-
### 작업 예산으로 무게 조절
|
|
253
|
-
|
|
254
|
-
프로젝트 지침 문서 **§5의 작업 예산** 표로 `/pm`의 왕복 횟수를 조절합니다. 기본값은 아래와 같고, 그대로 두면 지금까지의 동작과 같습니다.
|
|
255
|
-
|
|
256
|
-
| 항목 | 기본값 | 조절했을 때 |
|
|
257
|
-
|---|---|---|
|
|
258
|
-
| QA fix 재시도 횟수 | 3 | 줄이면 실패가 빨리 사용자에게 올라옵니다. `0`은 fix 없이 첫 QA 결과로 종료 |
|
|
259
|
-
| 계획 단계 | 분리 | `통합`은 planner 호출을 2회 → 1회로 줄입니다 |
|
|
260
|
-
|
|
261
|
-
`계획 단계 = 통합`이면 planner가 `pending.md`와 **권장안을 채택했다고 가정한 `plan.md`** 를 한 번에 씁니다. 사용자가 `진행`으로 답하면 planner를 다시 부르지 않고 곧바로 engineer로 넘어갑니다.
|
|
262
|
-
|
|
263
|
-
대신 사용자가 권장안을 뒤집으면 planner를 Phase 2로 다시 불러야 하므로 그만큼 계획 작성이 헛일이 됩니다. **권장안 채택률이 높은 작업에서만 이득**입니다. 그래서 기본값은 `분리`입니다.
|
|
264
|
-
|
|
265
252
|
## 모델 변경
|
|
266
253
|
|
|
267
254
|
기본값은 **부모 세션 모델 상속**입니다. 특정 단계만 다른 모델로 돌리고 싶으면 생성된 파일을 직접 수정하세요.
|
package/package.json
CHANGED
|
@@ -13,7 +13,7 @@ argument-hint: <task_id> [fix]
|
|
|
13
13
|
- `task_id` — 입력의 첫 토큰. **없으면 사용자에게 먼저 요청합니다.** 임의로 정하지 마세요.
|
|
14
14
|
- 모드 판단:
|
|
15
15
|
- **신규 구현** — `works/<task_id>/plan.md` 경로와 `decisions.md` 경로를 전달합니다. `plan.md`가 없으면 위임하지 말고 planner를 먼저 실행하라고 사용자에게 안내합니다.
|
|
16
|
-
- **QA Fix** — 입력에 `fix`가 있거나 `works/<task_id>/qa.md`가 FAIL/PARTIAL이면, `qa.md` 경로와 회차(`<N
|
|
16
|
+
- **QA Fix** — 입력에 `fix`가 있거나 `works/<task_id>/qa.md`가 FAIL/PARTIAL이면, `qa.md` 경로와 회차(`<N>/3`)를 전달합니다. 회차는 `engineer.md`의 기존 회차 섹션 수를 보고 계산합니다.
|
|
17
17
|
- 다음 지시를 함께 전달합니다: 구현 보고를 `works/<task_id>/engineer.md`에 회차별 append, **git 커밋/푸시 금지**.
|
|
18
18
|
|
|
19
19
|
## 이후 처리
|
|
@@ -35,12 +35,6 @@ argument-hint: <task_id> <작업 지시 또는 지시가 담긴 파일 경로>
|
|
|
35
35
|
- task_id는 디렉터리명이 됩니다. `/`, 공백, 그 외 경로에 쓸 수 없는 문자가 포함되면 그대로 쓰지 말고 사용자에게 되묻습니다.
|
|
36
36
|
- **임의로 정하지 마세요.**
|
|
37
37
|
|
|
38
|
-
### 작업 예산 확인
|
|
39
|
-
|
|
40
|
-
`{{PROJECT_DOC}}` §5의 **작업 예산** 표를 읽어 이번 워크플로우의 동작을 결정합니다. 표가 없거나 값이 비어 있으면 **QA fix 재시도 3회 / 계획 단계 분리**로 간주합니다.
|
|
41
|
-
|
|
42
|
-
읽은 값은 1단계 보고에 한 줄로 밝힙니다. 예: `작업 예산: fix 2회 / 계획 단계 통합`
|
|
43
|
-
|
|
44
38
|
## 작업 모드 판단
|
|
45
39
|
|
|
46
40
|
`works/<task_id>/`의 파일 존재 여부로 재개 지점을 판단합니다. 대화 컨텍스트가 없어도 이 판단만으로 이어서 진행할 수 있어야 합니다.
|
|
@@ -88,7 +82,6 @@ brief를 작성한 뒤 사용자에게 다음을 보고하고 **중단합니다.
|
|
|
88
82
|
- 목표: <한 줄>
|
|
89
83
|
- 범위 제외: <항목 나열 — 없으면 "없음">
|
|
90
84
|
- 확인 필요: <항목 나열 — 없으면 "없음">
|
|
91
|
-
- 작업 예산: fix <N>회 / 계획 단계 <분리 또는 통합>
|
|
92
85
|
|
|
93
86
|
이 브리프가 맞는지 확인해주세요. 수정할 부분은 파일을 직접 편집하셔도 됩니다.
|
|
94
87
|
확인되면 "진행"으로 회신해주세요.
|
|
@@ -98,10 +91,6 @@ brief를 작성한 뒤 사용자에게 다음을 보고하고 **중단합니다.
|
|
|
98
91
|
|
|
99
92
|
## 2단계: Discovery
|
|
100
93
|
|
|
101
|
-
작업 예산의 **계획 단계** 값에 따라 planner 호출 방식이 달라집니다.
|
|
102
|
-
|
|
103
|
-
### 계획 단계 = 분리 (기본)
|
|
104
|
-
|
|
105
94
|
planner를 Phase 1로 호출합니다.
|
|
106
95
|
|
|
107
96
|
```
|
|
@@ -120,29 +109,6 @@ plan/decisions는 작성하지 마세요.
|
|
|
120
109
|
- `works/<task_id>/pending.md` 경로
|
|
121
110
|
- 회신 형식 안내: "`D1=A, D2=B` 형식으로 회신해주세요"
|
|
122
111
|
|
|
123
|
-
### 계획 단계 = 통합
|
|
124
|
-
|
|
125
|
-
planner를 한 번만 호출해 미결정 분석과 계획 수립을 함께 받습니다.
|
|
126
|
-
|
|
127
|
-
```
|
|
128
|
-
Phase 1+2 (통합).
|
|
129
|
-
task_id: <task_id>
|
|
130
|
-
착수 브리프: works/<task_id>/pm-brief.md
|
|
131
|
-
|
|
132
|
-
미결정 사항을 분석해 works/<task_id>/pending.md를 작성하고,
|
|
133
|
-
각 항목의 권장안을 채택했다고 가정해
|
|
134
|
-
works/<task_id>/plan.md, decisions.md, followups.md까지 이어서 작성하세요.
|
|
135
|
-
decisions.md에는 각 결정이 권장안이며 사용자 미확인임을 명시하세요.
|
|
136
|
-
```
|
|
137
|
-
|
|
138
|
-
- **미결정 항목이 0개**면 계획서가 이미 확정입니다. 사용자 확인 없이 3단계 **2번(engineer)** 부터 진행합니다.
|
|
139
|
-
- 1개 이상이면 사용자에게 보고하고 **중단**합니다.
|
|
140
|
-
- 발견 항목 수 + 각 항목 한 줄 요약 (권장안 포함)
|
|
141
|
-
- "권장안을 전제로 `works/<task_id>/plan.md`까지 작성되어 있습니다."
|
|
142
|
-
- 회신 형식 안내: "권장안대로 진행하려면 `진행`, 바꿀 항목만 `D1=B` 형식으로 회신해주세요"
|
|
143
|
-
- 사용자가 `진행`으로 회신하면 **planner를 다시 부르지 않고** 3단계 **2번(engineer)** 부터 진행합니다.
|
|
144
|
-
- 사용자가 항목을 바꾸면 3단계 **1번(planner Phase 2)** 부터 진행합니다. 바뀐 항목뿐 아니라 **모든 결정의 최종값**을 전달하세요.
|
|
145
|
-
|
|
146
112
|
## 3단계: Execution
|
|
147
113
|
|
|
148
114
|
1. planner를 Phase 2로 호출합니다.
|
|
@@ -167,7 +133,7 @@ decisions.md에는 각 결정이 권장안이며 사용자 미확인임을 명
|
|
|
167
133
|
구현 보고는 works/<task_id>/engineer.md에 회차별 append로 남기세요.
|
|
168
134
|
git 커밋/푸시는 금지입니다.
|
|
169
135
|
```
|
|
170
|
-
3. **qa 호출 + Fix 루프.**
|
|
136
|
+
3. **qa 호출 + Fix 루프.** engineer fix 재호출은 **최대 3회**입니다. 따라서 engineer 호출은 최대 4회(신규 구현 1 + fix 3), qa 호출도 최대 4회(초회 1 + fix 후 재검증 3)입니다.
|
|
171
137
|
- qa 호출:
|
|
172
138
|
```
|
|
173
139
|
task_id: <task_id>
|
|
@@ -180,15 +146,14 @@ decisions.md에는 각 결정이 권장안이며 사용자 미확인임을 명
|
|
|
180
146
|
- **FAIL / PARTIAL**이면 engineer 재호출:
|
|
181
147
|
```
|
|
182
148
|
task_id: <task_id>
|
|
183
|
-
QA 실패. 회차: <N
|
|
149
|
+
QA 실패. 회차: <N>/3
|
|
184
150
|
QA 결과: works/<task_id>/qa.md
|
|
185
151
|
|
|
186
152
|
이 문서의 "실패 원인"과 "Fix 가이드"를 참고해 수정하세요.
|
|
187
153
|
Fix 결과는 works/<task_id>/engineer.md에 회차 섹션으로 append 하세요.
|
|
188
154
|
```
|
|
189
155
|
수정 후 qa 재호출.
|
|
190
|
-
-
|
|
191
|
-
- `<F>`가 `0`이면 fix 없이 첫 QA 결과로 4단계로 갑니다.
|
|
156
|
+
- **3회 fix 후에도 FAIL이면 루프를 중단하고 4단계로 갑니다.** 임의로 통과 처리하거나 상한을 넘겨 시도하지 마세요.
|
|
192
157
|
|
|
193
158
|
## 4단계: 완료 보고 (`pm-report.md`)
|
|
194
159
|
|
|
@@ -101,20 +101,6 @@ engineer는 구현 후, qa는 검증 시 아래 항목을 수행합니다. **명
|
|
|
101
101
|
- README는 **사용자에게 보이는 변화가 있을 때만** 갱신합니다. 내부 리팩터링·테스트 추가만으로는 건드리지 않습니다.
|
|
102
102
|
- `works/`를 git에 커밋할지: <커밋함 / 커밋하지 않음(.gitignore에 추가)>
|
|
103
103
|
|
|
104
|
-
### 작업 예산
|
|
105
|
-
|
|
106
|
-
pm이 워크플로우를 시작하기 전에 읽습니다. **아래는 기본값입니다.** 작업 규모·마감·리스크에 맞게 조정하세요. 표가 없으면 에이전트는 기본값으로 동작합니다.
|
|
107
|
-
|
|
108
|
-
| 항목 | 값 |
|
|
109
|
-
|---|---|
|
|
110
|
-
| QA fix 재시도 횟수 | 3 |
|
|
111
|
-
| 계획 단계 | 분리 |
|
|
112
|
-
|
|
113
|
-
- **QA fix 재시도 횟수** — QA가 FAIL / PARTIAL일 때 engineer를 재호출하는 최대 횟수입니다. 소진하면 pm은 임의로 통과시키지 않고 `미완료(에스컬레이션)`으로 보고합니다. `0`이면 fix 없이 첫 QA 결과로 종료합니다.
|
|
114
|
-
- **계획 단계** — planner를 몇 번 호출할지 결정합니다.
|
|
115
|
-
- `분리` — Phase 1(미결정 분석) → 사용자 결정 → Phase 2(계획 수립). 호출 2회, 정지 1회.
|
|
116
|
-
- `통합` — planner가 `pending.md`와 **권장안을 채택했다고 가정한 계획서**를 한 번에 작성합니다. 호출 1회, 정지 0~1회. 사용자가 권장안과 다르게 결정하면 Phase 2를 다시 호출해야 하므로 그만큼 계획 작성이 헛일이 됩니다. **결정이 뒤집힐 가능성이 낮거나 시간이 촉박할 때** 쓰세요.
|
|
117
|
-
|
|
118
104
|
## 6. 아키텍처 규칙
|
|
119
105
|
|
|
120
106
|
<없으면 "특별한 제약 없음"으로 남겨두세요.>
|
|
@@ -23,7 +23,7 @@ task_id는 PM이 전달합니다. **전달받지 못했으면 즉시 PM에게
|
|
|
23
23
|
|
|
24
24
|
## 입력 분기
|
|
25
25
|
|
|
26
|
-
PM 메시지에 `Phase 1` / `Phase 2`
|
|
26
|
+
PM 메시지에 `Phase 1` / `Phase 2` 중 하나가 명시됩니다. 없으면 즉시 PM에게 반환하고 중단합니다.
|
|
27
27
|
|
|
28
28
|
## Phase 1: Discovery
|
|
29
29
|
|
|
@@ -119,41 +119,11 @@ PM 메시지에 `Phase 1` / `Phase 2` / `Phase 1+2 (통합)` 중 하나가 명
|
|
|
119
119
|
- 주의사항: <engineer가 반드시 알아야 할 것 있으면>
|
|
120
120
|
```
|
|
121
121
|
|
|
122
|
-
## Phase 1+2: 통합
|
|
123
|
-
|
|
124
|
-
**목표**: 호출 1회로 미결정 분석과 계획 수립을 함께 끝냅니다. 시간이 촉박하거나 결정이 뒤집힐 가능성이 낮은 작업에 PM이 선택합니다.
|
|
125
|
-
|
|
126
|
-
### 절차
|
|
127
|
-
|
|
128
|
-
1. **Phase 1을 그대로 수행**해 `pending.md`를 작성합니다. 미결정 항목이 0개면 `pending.md`를 만들지 않습니다.
|
|
129
|
-
2. 이어서 **각 항목의 권장안을 사용자가 채택했다고 가정하고** Phase 2를 수행해 `plan.md` / `decisions.md` / `followups.md`를 작성합니다.
|
|
130
|
-
3. `decisions.md`의 각 행 "근거" 칸 끝에 **`(권장안 — 사용자 미확인)`** 을 붙입니다. 사용자가 실제로 승인한 결정과 구분되어야 합니다.
|
|
131
|
-
|
|
132
|
-
**권장안을 스스로 뒤집지 마세요.** Phase 1에서 권장한 옵션과 Phase 2에서 계획에 반영한 옵션이 달라지면 안 됩니다. 계획을 세우다 권장안이 틀렸다고 판단되면, 계획을 바꾸지 말고 `pending.md`의 권장안을 고친 뒤 그 값으로 계획을 세우고 응답에 그 사실을 밝히세요.
|
|
133
|
-
|
|
134
|
-
### Phase 1+2 응답 (PM에게)
|
|
135
|
-
|
|
136
|
-
```
|
|
137
|
-
## Phase 1+2 완료: <task_id>
|
|
138
|
-
|
|
139
|
-
- 발견 항목: <N>개 (권장안 반영 완료, 사용자 미확인)
|
|
140
|
-
- 작성 파일: works/<task_id>/pending.md, plan.md, decisions.md, followups.md
|
|
141
|
-
- 작업 단위: <N>개 (T1~T<N>)
|
|
142
|
-
- 영향 범위: 신규 <X>파일, 수정 <Y>파일, 데이터 변경 <있음/없음>
|
|
143
|
-
|
|
144
|
-
### 항목 요약
|
|
145
|
-
- D1. <제목> — 권장(반영): <옵션>
|
|
146
|
-
- D2. <제목> — 권장(반영): <옵션>
|
|
147
|
-
|
|
148
|
-
### 결정이 뒤집히면 영향받는 작업 단위
|
|
149
|
-
- D1 → T2, T5
|
|
150
|
-
```
|
|
151
|
-
|
|
152
122
|
## 금지 사항
|
|
153
123
|
|
|
154
124
|
- **코드 작성 / 수정 금지.** Write / Edit는 `works/<task_id>/` 안에서만 사용합니다.
|
|
155
125
|
- `works/<task_id>/pm-brief.md`, `pm-report.md` 수정 금지 (PM 산출물이며, brief는 사용자가 확인한 문서입니다). brief가 잘못되었다고 판단되면 고치지 말고 PM에게 반환하세요.
|
|
156
126
|
- PM이 전달한 참고 문서(기능 정의서 등) 수정 금지.
|
|
157
127
|
- 사용자 결정 없이 미결정 사항 임의 결정 금지.
|
|
158
|
-
- **Phase 1**에서 plan / decisions 작성 금지 (`pending.md`만).
|
|
128
|
+
- **Phase 1**에서 plan / decisions 작성 금지 (`pending.md`만).
|
|
159
129
|
- git 변경 명령 금지 (`git status`, `git diff`, `git log`는 허용).
|