작업 흐름(Flujo de tareas)
각 상태 변경 규칙은 references/estados.md에 있습니다: 변경 사항별로 하나의 카드, 언제, 누가, 어떤 권한이 필요한지, 저장소에서 무엇을 하는지, 순서가 명시되어 있습니다. 이 파일은 사용 방법을 설명합니다.
큐 변경 방법
큐의 모든 쓰기는 CLI를 통해서만 이루어집니다. 수동으로 절대 하지 마십시오:
python -I -X utf8 "$HOME/.claude/sf/cola.py" [--raiz RUTA] [--quien propietario|principal] [--via cli|panel] [--json] <명령어> …
- 항상 이 명령을 사용하며, bash, zsh, PowerShell에서 동일하게, 모든 프로젝트에서 동일하게 사용합니다. 서브에이전트도 마찬가지입니다. 모드가 세션 시작 시 이 시스템에서 Python이 다른 이름(macOS의 경우
python3)으로 실행된다고 말하면, 그 이름을python대신 사용합니다. 여기서와 SF의 모든 Python 명령에서 동일합니다(「Python 명령은 감지된 인터프리터에서 나온다」, 236).cola.py encargo도 이를 알려줍니다. 특정 폴더의tools/cola.py는 사용하지 마십시오(SF에서는plugins/sf/tools/cola.py가 활성 브랜치에 따라 변경됩니다). 로드 시 패널은 자체cola.py를~/.claude/sf/cola-<세션>.py에 복사하고 실행합니다(「패널은 로드 시 생성된 cola.py 복사본을 실행한다」, 136).~/.claude/sf/cola.py는CLAUDE_CODE_SESSION_ID를 통해 명령을 해당 복사본에 전달하는 실행기입니다. Claude와 패널은 동일한 세션 ID를 사용합니다(작업 252). 복사본이 없으면 2로 종료하며 메시지를 출력합니다./reload-plugins로 다시 생성합니다. --raiz: 프로젝트 폴더, 기본값은 현재 폴더입니다. 테스트 시 큐 복사본의 경로를 지정합니다.--quien: 기본값은principal입니다.propietario는 변경 사항이 소유자의 결정(예: 마감 승인)일 때 사용합니다.- 종료 코드: 0(변경 성공), 1(변경 실패, 이유 출력, 아무것도 건드리지 않음), 2(명령어 형식 오류).
choques는 조회 전용이며, 충돌이 있으면 3을 반환합니다.cola.py <명령어> -h로 각 명령어의 사용법을 확인할 수 있습니다.
CLI가 각 쓰기 시 수행하는 작업: 큐 잠금(.sf/peticiones.lock), 변경 전 복사본을 .sf/copias/(최대 50개)에 저장, 작업의 historial에 변경 기록, 작업이 큐에서 제거되면 해당 작업과 기록을 .sf/historial.jsonl로 이동. 번호는 재사용되지 않습니다.
CLI가 처리하지 않는 규칙
CLI는 각 변경의 조건(시작 상태, 브랜치, 단계, git)을 적용합니다. 대화 중 언제, 어떻게 사용할지(등록 시 메뉴, 진행 중 설정, 서브에이전트 실행 및 회수, 테스트 및 마감 제안, 병합 및 재설명 제안, 문서 작업, 자유 작업)는 sf:orquestacion 스킬에 설명되어 있습니다. 여기서는 큐 자체와 관련된 내용을 다룹니다:
- 소유자만이 큐를 씁니다. 서브에이전트는 쓰기 명령을 실행하지 않고, 보고서에 명시하며 소유자가 실행합니다.
- 모든 요청은 '진행 중'인 작업 하에 이루어집니다. 그렇지 않으면 작업을 시작하지 않습니다. 큐 재구성(병합, 분할, 재설명, 단계 추가, 유형 변경)에는 이 규칙이 적용되지 않습니다(「작업당 하나의 활성 서브에이전트를 사용한 오케스트레이션」, 149).
- 소유자의 승인:
cerrar,a-observacion,reobservar,descartar명령은 소유자의 승인이 필요합니다. 진행 중인 작업을en-cola로 되돌릴 때도 승인이 필요하지만, 작업 브랜치(또는 서브에이전트의 보조 브랜치)에 자체 커밋이 있는 경우에 한합니다. 작업 브랜치가 비어 있거나 이미 삭제된 경우en-cola는 브랜치를 삭제하고 빈 서브에이전트를 회수합니다(275). - 생성 시 유형 (
crear --tipo): deliberar(숙의), documentar(문서화), diseñar(설계), implementar(구현), especificar(명세), corregir(수정), investigar(조사). 변경 시tipo N T를 사용합니다. en-curso전 충돌 확인:choques N명령으로,--archivos와 예상 파일을 지정합니다. 아직 브랜치가 없는 경우 설명에서 유추합니다. 이미 진행 중인 작업의 서브에이전트 실행 시에는 충돌 확인을 하지 않습니다(「진행 중으로 설정 시 충돌 예측」, 130).- 첫 번째 활성화 전 브랜치 생성 (
rama), 경고 메시지 출력. 서브에이전트의 경우 소유자가 브랜치를 활성화하지 않고 생성하고(rama --sin-activar), 서브에이전트 실행 전에 기록합니다. 서브에이전트는 이 브랜치에서 보조 브랜치를 만들어 작업하며, 소유자는git merge --ff-only로 병합합니다. 서브에이전트는 작업 브랜치를 워크트리에서 활성화하지 않습니다. 이렇게 하면 T와 C가 설정된 워크트리에서 작동합니다(「작업당 하나의 활성 서브에이전트를 사용한 오케스트레이션」, 149). - 서브에이전트 회수: CLI가 처리하며,
subagente로 기록된 워크트리와 브랜치를 사용합니다(--worktree는 프로젝트 기준 상대 경로 허용). 작업이 서브에이전트 없이 남게 되는 모든 명령에서 수행됩니다:cerrar,a-observacion,descartar,eliminar,a-propuesta,revertir,limpiar,reabrir, 그리고 흡수되는 작업의 경우fusionar(보조 브랜치가 이미 남는 브랜치에 병합된 경우에만. 남는 작업은 자체 서브에이전트를 유지). 강제 아님: 커밋되지 않은 변경 사항이 있는 워크트리,develop에 병합되지 않은 커밋이 있는 보조 브랜치, 또는 병합 시 통합되지 않은 브랜치는 남겨지고 경고합니다. 반면descartar와limpiar는 모든 것을 제거합니다.cerrar와a-observacion은 보조 브랜치에 작업 브랜치로 가져오지 않은 커밋이 있으면 거부하고, 가져오는 방법을 알려줍니다.reabrir는 커밋되지 않은 변경 사항도 경고 없이 모두 정리합니다. 기록:recogida또는recogida-con-avisos. 소유자는 서브에이전트를 중지하고 경고를 처리하기만 하면 됩니다(「cola.py는 작업이 서브에이전트 없이 남을 때 서브에이전트를 회수한다」, 169). - 커밋 서명 (「마감 커밋 서명은 설정 가능, 설정하지 않으면 서명 줄 없음」, 238):
cerrar와a-observacion의 스쿼시 커밋,decision커밋, RELEASE 버전 커밋은.sf/proyecto.json의coautor줄을 포함합니다(SF 자체의 경우:Co-Authored-By: Claude Opus 5.5 <[email protected]>).cerrar,a-observacion,decision,encargo명령은--coautor "…"를 허용하며, 설정된 값을 덮어씁니다. 없으면 커밋은 공동 저자 줄 없이 진행됩니다. - 소유자의 결정:
decision "제목" --archivo RUTA|--texto T [--numero NNN] [--coautor "Co-Authored-By: …"] [--push]는 큐를 건드리지 않습니다.develop의docs/decisiones/에서 다음 번호를 부여하고NNN-YYYY-MM-DD-제목.md이름을 생성합니다(--numero지정 시 해당 번호로 다시 쓰되 이름은 변경하지 않음). 파일을 쓰고(텍스트, 앞에# 제목이 없으면 추가, 있으면 일치해야 함),README.md를 다시 만들고develop에커밋 Decision NNNN: 제목을 만듭니다. 다른 활성 브랜치가 있어도 작업 복사본을 변경하거나 건드리지 않으며,a-propuesta와 유사합니다(작업 273).develop이 다른 워크트리에 있거나 활성 상태에서docs/decisiones/에 커밋되지 않은 변경 사항이 있으면 실행되지 않습니다.develop이 활성 상태이면README.html도 다시 만듭니다.--push는develop을 푸시하고 번호와 해시를 출력합니다. git이 없거나develop이 없으면 파일만 쓰고 경고합니다(작업 283). - 병합 및 분할은 소유자가 작성합니다(패널에서
/sf_fusionar,/sf_split). 소유자는fusionar로 동일한 문서를 업데이트하는 두 작업만 병합할 수 있습니다(「업데이트할 문서당 하나의 작업」, 142).
시점별 명령어
| 시점 | 명령어 |
|---|---|
| 등록 및 시작 | crear, choques, en-curso, en-cola, rama |
| 작업 중 | paso añadir, paso marcar, paso quitar, renombrar, tipo, subagente, informe |
| 테스트 | listo, comprobado, probar |
| 마감 | cerrar, a-observacion |
| 관찰 중 | observando, seguir, cerrar, reobservar, 문제 발생 시 revertir |
| 취소 | descartar, limpiar, revertir, reabrir, eliminar, restaurar, a-propuesta |
| 병합 및 분할 | fusionar, split |
| 조회 및 복사 | lista, ver, copias, recuperar |
| 큐 외부 | decision |
모든 마감 (cerrar, a-observacion)은 브랜치 유무와 관계없이(제안도 포함) '작업 마감' 단계를 요구하며, '테스트를 위한 브랜치 활성화' 외에는 다른 미완료 단계가 없어야 합니다. 두 마감 단계는 작업이 진행 중 상태가 될 때(crear --en-curso, en-curso, reabrir, probar(큐에서), restaurar, fusionar) cola.py가 한 번, 마지막에 추가하며 제거되거나 텍스트가 변경되지 않습니다. 아직 이 단계가 없는 진행 중인 작업은 큐 로드 시 받게 됩니다. 새 작업 단계가 추가되면 '테스트를 위한 브랜치 활성화' 단계가 완료되었더라도 다시 미완료로 설정됩니다. 테스트 도우미 단계(paso añadir N "texto" --prueba)는 두 마감 단계 사이에 위치하며, 마감에 필수적이지 않으며 추가해도 '브랜치 활성화' 단계가 다시 미완료로 설정되지 않습니다(「테스트 도우미: 브랜치 활성화 후, 마감에 필수 아님」, 184). listo는 테스트할 내용을 저장할 뿐입니다(「마감 단계: 작업이 진행 중 상태가 되는 시점부터」, 174). probar는 develop을 브랜치에 병합하고(충돌 시 되돌리고 활성화하지 않음, sub-NN의 커밋을 가져오지 않은 경우 병합 및 활성화하지 않음), 브랜치를 활성화하거나 이미 활성화된 경우 유지하며 '테스트를 위한 브랜치 활성화'를 완료로 표시합니다. 소유자의 승인은 마감입니다(172, 121). 단계는 1부터 번호가 매겨지며 ver의 n과 같습니다. 큐에서 제거된 작업은 .sf/historial.jsonl에 제거된 상태(cerrada, eliminada, absorbida, descartada, revertida)로 기록되며 ver로 확인할 수 있습니다.
되돌리기는 대상을 지정해야 합니다: revertir N --eliminar는 작업을 흔적 없이 큐에서 제거합니다(E와 동일). revertir N --pendiente는 작업을 큐에 다시 넣고, 브랜치 없이 재개합니다. '마감됨(R)' 상태로 남지 않습니다(「되돌리기는 작업을 제거하거나 대기 상태로 둠」, 134). 소유자가 지정하지 않으면 물어보십시오.
git 관련 오류(스쿼시 또는 되돌리기 시 충돌, 커밋되지 않은 변경 사항, 다른 워크트리의 브랜치)로 명령이 실패하면 CLI가 되돌리고 원인을 알려줍니다. 소유자가 문제를 해결하고 명령을 다시 실행합니다. 푸시 실패는 마감을 막지 않습니다. 기록에 push-fallido로 남고 수동으로 다시 푸시합니다.