요구사항 구현 (폴더 구조 + 로그)

이미 분석이 완료된 요구사항을 구축하기 시작할 때 적용되는 일반 지침입니다. (분석 단계가 아닙니다.)

이 패턴은 RV2-054-132-019_ ADG 프로세스 통합 (CONSUBANCO)에서 처음 적용된 패턴을 기반으로 재구성되었습니다. 이 스킬은 이식 가능합니다: 사용되는 프로젝트/클라이언트에 관계없이 동일하게 적용되며, §0의 앵커 규칙을 따릅니다.

0. 이 문서의 위치 (프로젝트 간 이식성)

이 프롬프트는 절대 경로나 특정 클라이언트 이름을 가정하지 않습니다. 사용되는 모든 프로젝트에서 유효한 앵커 규칙은 다음과 같습니다:

해당 프로젝트/클라이언트의 모든 요구사항을 그룹화하는 폴더가 항상 존재합니다. 리터럴 이름은 다를 수 있습니다 (Req\, Requerimientos\ 또는 사용자가 새 프로젝트에서 처음 작업할 때 지정하는 다른 이름). 이 폴더 내에는 요구사항당 하나의 하위 폴더가 있으며, 해당 코드로 이름이 지정됩니다 (예: RV2-054-132-019, 때로는 _<짧은 이름>이 붙음, 예: RV2-054-132-019_ ADG 프로세스 통합).
이 문서의 다른 모든 항목 (README.md, Compartidos\, EchasXC\, SCRIPTS\...)은 상위 컨테이너 폴더의 이름과 관계없이 해당 특정 요구사항의 하위 폴더에 상대적입니다. 컨테이너 폴더 이름을 매번 물어볼 필요는 없습니다. 프로젝트에 이미 존재하는 경우 (Req\ 또는 Requerimientos\), 해당 폴더를 사용하고, 아직 존재하지 않는 경우 (새 프로젝트), 만들기 전에 사용자에게 이름을 물어보십시오.
새롭고 별개의 요구사항(§10 참조)은 해당 컨테이너 폴더 아래에 자체 하위 폴더를 가지고 있거나 필요로 하는 것으로 식별됩니다. 동일한 클라이언트/모듈에 있더라도 다른 기존 요구사항의 폴더 안에 절대 넣지 않습니다.

구체적인 트리 (§1-§4의 모든 항목은 요구사항 폴더에서 직접 시작되며, 이 트리가 표시하는 수준보다 위나 아래에 아무것도 존재하지 않습니다):

Req\                                     (또는 "Requerimientos\", 프로젝트에서 사용하는 이름)
└─ RV2-054-132-019_ ADG 통합\             ← 요구사항 폴더(§0), 다른 모든 것의 앵커
   ├─ README.md                         ← §1, 로그
   ├─ Compartidos\                      ← §2, HU/이미지/증거/키
   ├─ EchasXC\                     ← §4, Claude가 생성하는 모든 비공식 산출물
   │  └─ SCRIPTS\                       ← §3, Claude의 작업 폴더 (루트 아님)
   │     ├─ ORG\                       ← 롤백, 자체 번호
   │     └─ MOD\
   │        ├─ ALTERS\                 ← 테이블 전용
   │        ├─ SP\                     ← 저장 프로시저 전용
   │        ├─ FN\                     ← 함수 전용
   │        └─ VI\                    ← 뷰 전용
   ├─ SCRIPTS\                          ← 사용자가 선별하는 루트 폴더(§3), 허가 없이 수정 금지
   ├─ Analisis_Impacto_[코드].docx       ← 분석 단계 산출물 (요청된 경우)
   ├─ Estimacion_tiempos_[코드].xlsx
   └─ Plan_Implementacion_[코드].docx

1. 변경 로그 — 요구사항 폴더 루트의 `README.md`

무언가를 구축/수정하거나, 해결되었거나 추가된 미해결 질문이 있거나, 상태가 변경될 때마다 매번 업데이트되는 단일 라이브 파일입니다. 고정 구조:

요구사항 코드 및 이름 + "마지막 업데이트: YYYY-MM-DD"가 있는 헤더.
이것이 무엇인가 — 요구사항에 대한 2-4줄 요약.
일반 상태 — 이미 구축된 것 — 단계/모듈별로 하나의 글머리 기호로, 구축됨 / 부분적 / 보류 중으로 표시.
아키텍처 (각 항목의 위치) — 화면 경로, 주요 SP (플래그 포함), 작업, 주요 테이블, 구성 파일. DB 접속 정보(서버, 데이터베이스 이름, 사용자 및 비밀번호)는 여기나 어떤 파일에도 문서화되지 않습니다. 포털/프로젝트에 따라 변경되며, 사용자는 필요할 때 비밀번호와 함께 제공합니다(§7 참조).
보류 사항 — "클라이언트에 대한 질문" (해결되면 ~~텍스트~~로 취소선 표시, 삭제하지 않음)과 "보류 중인 개발"로 구분됩니다.
변경 로그 — 세션/날짜별 항목 (**YYYY-MM-DD (짧은 제목)**), 가장 최근 항목이 위에 있으며, 다음을 포함: 발견된 실제 허점/버그, 결정된 사항 및 이유, 변경된 파일, 사용자가 수행해야 할 작업 (스크립트 실행, 재컴파일, 화면 테스트).

Analisis_Impacto_[코드].docx 또는 Plan_Implementacion_[코드].docx를 대체하지 않습니다 (이는 분석 단계의 산출물입니다). 이 README는 구축의 실시간 상태입니다.

너무 커질 경우 순환 — README.md가 약 200KB에 가까워지거나 초과하면, 추가하기 전에 오래된 세션을 보관합니다 (실제 사례: README.md가 256KB를 초과하여 읽기 도구가 열 수 없게 되었습니다). 방법: 가장 오래된 로그 항목을 새 파일 README_historico_YYYY.md (연도별 또는 필요에 따라)로 이동하고, 활성 README.md에는 가장 최근의 ~10-15개 세션과 보관된 내용에 대한 2-3줄 요약만 남깁니다 (연속성을 잃지 않도록). 다른 섹션(이것이 무엇인가, 일반 상태, 아키텍처, 보류 사항)은 절대 보관되지 않으며 항상 활성 파일에 남아 있습니다. 세션 로그만 순환됩니다.

2. `Compartidos\` 폴더

클라이언트/외부 공급자와 공유되는 입력 자료 또는 증거로, 코드가 아닌 모든 것: HU 및 그 부속 자료, 문서에서 추출된 임베디드 이미지/스크린샷, 키(PGP/인증서), 데이터 매핑 파일, 제3자로부터 수신되거나 제3자에게 전송된 테스트 파일(예: CDC).

Compartidos\에 현재 요구사항과 관련 없는 주제의 문서가 나타나는 경우(예: "통합 ADG 프로세스" 폴더 내의 "로그/감사" HU): 두 가지 쉬운 출력을 가정하지 마십시오. 즉, 단지 거기에 있다고 해서 이 요구사항의 증거로 취급하거나, 자의로 무시/이동하지 마십시오. 사용자에게 다음 세 가지 경우 중 어느 것인지 질문하십시오:

잘못 배치됨 — 다른 폴더에 속하며, 실수로 복사되었습니다.
새롭고 별개의 요구사항으로 아직 자체 폴더가 없는 경우 — 이와 동일한 구조로 하나를 만들고, 현재 요구사항과 DB 개체/화면을 공유하는 경우 두 요구사항의 "관련 요구사항"(§10)에 문서화합니다.
의도적으로 하나의 클라이언트 폴더에 그룹화된 요구사항 집합 (이 패턴의 선례는 QA 전달 이메일 템플릿에 존재하며, 명시적으로 "요구사항 집합"을 포함합니다) — 그렇다면 코드별 하위 폴더가 여전히 적절한지 확인합니다.

3. 스크립트 폴더 — `SCRIPTS\ORG\` 및 `SCRIPTS\MOD\`

요구사항 폴더에는 두 개의 개별 SCRIPTS 폴더가 있습니다: <요구사항>\SCRIPTS\ (루트) 및 <요구사항>\EchasXC\SCRIPTS\. Claude가 구축하면서 각 스크립트를 배치하는 작업 폴더는 EchasXC\SCRIPTS\입니다. 사용자는 EchasXC\SCRIPTS\에서 승격하여 수동으로 루트 SCRIPTS\ 폴더를 선별합니다. 사용자가 명시적으로 요청하지 않는 한 해당 루트 폴더를 건드리지 마십시오.

MOD\ — 개체 유형별 하위 폴더, 그룹화되지 않음, 각각 자체적이고 독립적인 순차 번호를 가집니다 (서로 번호를 공유하지 않음):

MOD\ALTERS\ — 테이블 전용 (CREATE TABLE / ALTER TABLE).
MOD\SP\ — 저장 프로시저 전용.
MOD\FN\ — 함수 전용 (CREATE FUNCTION).
MOD\VI\ — 뷰 전용.
전용 폴더가 없는 개체 유형(인덱스, 트리거, 작업 등)이 나타나는 경우, 어디에 들어갈지 가정하거나 "비슷해 보이는" 폴더에 넣지 말고 사용자에게 폴더 이름을 어떻게 지정할지 질문하십시오. (한 번 실제로 발생한 오류: 함수가 처음에 SP\에 배치되었다가 ALTERS\에 배치되었고, 결국 사용자가 전용 FN\을 요청했습니다.)
모든 항목의 명명 패턴: 수정되는 기존 개체 → N_NOMBRE_MOD.sql; 완전히 새로운 개체 (DB에 존재하지 않음) → N_NOMBRE_NEW.sql.

ORG\ — 수정되는 개체의 롤백 (_NEW는 여기에 쌍이 없습니다: 새 항목의 롤백은 단순히 삭제하는 것이며, 캡처할 이전 항목이 없습니다). 기존 개체를 건드리기 전에 현재 DB에 있는 대로의 현재 정의를 추출하여 여기에 저장하십시오. 해당 파일이 롤백입니다.

ORG\는 MOD\의 숫자 미러가 아닙니다. 그렇게 가정하기 쉽고 잘못된 것입니다. 독립적인 번호를 가집니다. 자체 내에서 범주별로 번호를 매길 수도 있습니다 (예: 종속성을 존중하는 단일 패스의 모든 MOD\ALTERS에 대한 통합 롤백, 그리고 건드린 각 SP에 대한 별도의 롤백). ORG\의 번호 지정 체계를 가정하기 전에 사용자에게 확인하십시오. "MOD와 같은 번호" — 이전에 잘못 가정하여 한 번 수정되었습니다.
개체를 건드리거나 배포할 때마다 사용자에게 어떤 개체인지(이름) 명시적으로 알려서 무엇이 이동되었는지 분명히 하십시오.

이 섹션의 모든 스크립트에 대한 일반 규칙:

DDL은 항상 멱등적이어야 합니다 (IF NOT EXISTS / COL_LENGTH(...) IS NULL).
다른 새 SP를 호출하는 새 SP는 종속성과 동일한 파일/배치에 정의되며, 절대 이후 파일 번호에 정의되지 않습니다.
증분 스크립트가 나중에 "통합"/정리되는 경우 (나중에 별도의 ALTER를 통해 추가된 열이 원래 CREATE로 다시 접힘): 백업 ALTER는 이미 완전한 CREATE 아래에 그대로 둡니다 (두 경로가 공존하며, 하나가 선택되지 않음). 해당 ORG는 이미 개체의 전체 DROP을 수행하는 경우 변경할 필요가 없습니다. 열별로 롤백을 수행하는 경우 순서를 검토하십시오 (인덱스/제약 조건은 롤백에서 열을 건드리기 전에 삭제되고, 생성 시 최종 null 허용 여부를 설정한 후에 생성됨).

4. 비공식 작업 자료 — `EchasXC\`

Claude가 구축을 지원하기 위해 생성하지만 클라이언트나 팀에 공식적으로 전달되지 않는 모든 것 (검증 쿼리, 수동 테스트, 기술 시트, 초안 이메일): Compartidos\ 및 공식 산출물과 분리된 EchasXC\ 하위 폴더에 넣습니다.

5. 인코딩 — 어떤 이유로도 파일에 이미 설정된 인코딩을 수정하지 마십시오

악센트가 있는 모든 파일(.aspx/.aspx.vb/.master/스크립트 등)을 편집하기 전에 파일이 선언하거나 file 명령이 그렇게 보고한다고 해서 UTF-8이라고 가정하지 마십시오. 일부 레거시 포털의 오래된 파일은 실제로 내부적으로 ISO-8859-1/Windows-1252입니다 (악센트가 단일 상위 바이트). 표준 Edit/Write 도구는 전체 파일을 UTF-8로 디코딩/재작성합니다. 저장하는 즉시 파일 전체(편집 근처뿐만 아니라)의 모든 기존 악센트가 자동으로 그리고 영구적으로 깨집니다 (U+FFFD, 브라우저에서 "ï¿½" 또는 유사하게 표시됨).

이러한 파일을 건드리기 전에 실제 인코딩을 확인하십시오 (file archivo.aspx, 참고: 이미 손상된 파일은 실제로 그렇지 않더라도 깨끗한 "UTF-8"을 보고할 수 있습니다).
ISO-8859-1인 경우 [System.Text.Encoding]::GetEncoding("ISO-8859-1")을 사용하여 PowerShell을 통해 편집하십시오. 해당 인코딩으로 원시 바이트를 디코딩하고, 메모리에서 바꾼 다음, 동일한 인코딩으로 다시 쓰십시오. 이 의심이 드는 파일에는 절대 표준 Edit/Write 도구를 사용하지 마십시오.
매 편집 후에 확인하십시오. 편집 전에만 확인하지 마십시오. 리포지토리에 git이 있는 경우, 직후에 git diff --stat를 실행하십시오. 변경하려고 시도한 양보다 훨씬 많은 삭제 수는 예상된 편집이 아닌 손상 신호입니다. git이 없는 경우, 전후 파일 크기를 비교하십시오.
이미 실수로 손상된 경우: git checkout -- archivo로 되돌린 후(원본 바이트를 그대로 복구) 올바른 방법으로 다시 시도하십시오. 손실된 악센트는 덮어쓰면 복구할 수 없습니다.
Claude가 생성하는(편집하지 않는) 새 파일의 경우: 프로젝트에서 요구하는 경우 명시적 BOM UTF-8을 사용합니다 (해당되는지 사용자에게 확인).

6. 일반적인 자세 — 시니어처럼 행동하고, 절대 당연시하지 마십시오

무언가가 "그렇게 작동해야 한다"거나, 패턴이 다른 곳과 동일하게 반복된다거나, 데이터/스키마가 기억이나 피상적 읽기가 암시하는 것이라고 가정하지 마십시오. 항상 실제 프로세스를 검증하십시오:

스키마, 데이터 또는 동작을 단언하기 전에 실제 DB(DEV)에 대해 검증하십시오. 가정하지 말고 조회하십시오.
화면/SP가 수행하는 작업을 단언하기 전에 실제 코드(grep/파일 읽기)에 대해 검증하십시오. 이름이나 첫 번째 읽기를 신뢰하지 마십시오.
"필요해 보이는" 것을 추가하기 전에 요구사항의 HU/문서에 대해 검증하십시오. 명시되지 않은 경우 관성으로 구축하지 마십시오.
각 변경 사항의 결과를 검증하십시오 (SET PARSEONLY ON, git diff, 테스트 실행). 논리가 올바르게 보인다고 해서 컴파일/실행이 잘되었다고 가정하지 마십시오.

7. DB에 대한 실행 규칙 (스크립트 DDL뿐만 아니라 모든 것에 적용됨)

DB에 대해 INSERT/UPDATE/DELETE/DDL을 절대 실행하지 마십시오. DEV에서도, 채팅에서 명시적 확인을 받은 경우에도 마찬가지입니다. 사용자가 DB에 작성하는 모든 것을 직접 실행합니다. Claude의 역할은 스크립트를 준비하고, 사용자가 실행한 후에 SELECT로 예상대로 되었는지 확인하는 것입니다. 이는 ORG/MOD 폴더 규칙과 별개입니다. 카탈로그, 테스트 데이터, 모든 쓰기에도 적용됩니다.
읽기 전용 쿼리(SELECT, INFORMATION_SCHEMA, sys.sql_modules)는 매번 허가를 요청하지 않고 자유롭게 사용할 수 있습니다.
DB 서버, 데이터베이스 이름, 사용자 및 비밀번호는 어떤 파일에도 문서화되지 않습니다 (README.md, Compartidos\, .sql 스크립트, 코드 주석). 특정 데이터베이스 이름은 포털/프로젝트에 따라 변경되므로, 문서화할 가치가 있는 고정 값이 없습니다. 사용자는 필요할 때 채팅에서 비밀번호와 함께 제공하며, 해당 세션의 명령에 환경 변수로만 사용됩니다. 다음 번에 다시 요청하고, "다시 묻지 않기 위해" 저장하지 마십시오. 이미 비밀번호/연결이 있는 경우...

[잘림: 번역 완료]

8. 버전 및 명명 규칙 — 각 요구사항의 산출물에 대한 독립적인 버전 관리

각 요구사항은 자체적인, 점진적인 버전 체계를 가집니다. 크게 생각하고 모든 것을 "v1.0"으로 레이블 지정하지 마십시오.

README.md 자체의 첫 번째 버전은 v1.0입니다.
각 주요 변경 사항(새로운 세션 로그 항목)은 부 버전을 증가시킵니다: v1.1, v1.2...
산출물 재작업 또는 주요 구조 변경은 주 버전을 증가시킵니다: v2.0, v3.0...
버전 번호는 README.md 헤더에 기록됩니다.
Compartidos\의 파일은 YYYY-MM-DD_원본이름_vX.Y.ext 패턴을 따릅니다.
스크립트 폴더(MOD\)의 파일은 이미 자체 번호 체계를 가지고 있습니다. 스크립트 파일에 추가 "README 버전"을 접두사로 붙이지 마십시오.

9. Git 사용 규칙

이 워크플로우가 적용되는 프로젝트는 git 리포지토리를 사용합니다. Claude의 책임:

커밋하지 마십시오. Claude는 git add/commit을 실행하지 않습니다. 사용자가 변경 사항을 검토하고 수동으로 커밋합니다.
변경 사항을 분리하여 유지하십시오. 모든 작업은 EchasXC\ 폴더에서 수행되며, 사용자가 SCRIPTS\로 승격합니다. Claude는 루트 SCRIPTS\를 건드리지 않습니다.
변경 사항을 명확하게 설명하십시오. 수행된 작업을 요약하는 git diff --stat 스냅샷을 로그에 제공합니다.
Git 히스토리를 존중하십시오. 이미 존재하는 파일을 수정할 때 절대 git rebase나 git commit --amend를 수행하지 마십시오. 마지막 커밋 이후의 변경 사항으로 작업하고, 사용자가 수동으로 커밋하도록 남겨둡니다.

10. 여러 요구사항 처리

새롭고 별개의 요구사항이 이전 요구사항의 컨텍스트 내에서 식별되는 경우:

해당 컨테이너 폴더 아래에 자체 하위 폴더를 만듭니다.
이 문서의 전체 구조 (README, Compartidos, EchasXC/SCRIPTS, SCRIPTS)를 새 폴더에 복제합니다.
원래 요구사항의 README.md의 "관련 요구사항" 섹션과 새 요구사항의 README.md에 교차 참조를 추가합니다.
새 요구사항이 DB 개체를 공유하는 경우 MOD\ 하위 폴더에도 별도의 번호 체계가 있음을 문서화합니다.

11. 폴백 및 예외

사용자가 언제든지 이러한 규칙의 예외를 요청할 수 있습니다. Claude의 기본 자세:

요청된 예외를 수용합니다.
규칙에서 벗어난다는 사실을 README.md 로그에 명시적으로 문서화하여 기록을 유지합니다.
예외가 시간이 지남에 따라 패턴이 되는지 확인하고, 그렇다면 Claude는 업데이트된 지침을 요청해야 합니다.

Skill markdown은 CONSUBANCO 프로젝트의 실제 워크플로우 패턴을 기반으로 합니다. 실제 배포 전에 항상 팀 규칙과 대조하여 확인하십시오.

부록 A: 빠른 참조 — 일반적인 명령어

작업	명령어/액션
새 요구사항 시작	"empecemos a construir" 또는 "ya tengo el análisis aprobado"
DB 객체 열기	`type <파일경로>` 또는 `cat <파일경로>`
객체 정의 확인 (기존)	데이터베이스에 대해 `SELECT OBJECT_DEFINITION(OBJECT_ID('dbo.객체이름'))` 실행
스크립트 버전 확인	`EchasXC/SCRIPTS/MOD/<유형>/`의 파일 나열
인코딩 확인	`file <파일경로>`
변경 사항 검증	`git diff --stat` (git 사용 시)
롤백 생성	수정 전에 `ORG\`에 현재 객체 정의 저장

부록 B: DB 인코딩 문제 해결

PowerShell을 통한 ISO-8859-1 파일 편집 예시:

$content = [System.IO.File]::ReadAllBytes("경로/파일.aspx")
$encoding = [System.Text.Encoding]::GetEncoding("ISO-8859-1")
$text = $encoding.GetString($content)
# 여기서 $text 수정
$modifiedContent = $encoding.GetBytes($text)
[System.IO.File]::WriteAllBytes("경로/파일.aspx", $modifiedContent)

부록 C: ORG 폴더 번호 예시

잘못된 가정 (하지 마세요): MOD\ALTERS\1_TABLA_MOD.sql, MOD\SP\2_PROC_MOD.sql → ORG\는 ORG\1_TABLA.sql, ORG\2_PROC.sql을 가져야 함. 올바른 접근 방식: 사용자에게 확인.

ORG가 단일 파일로 통합된 경우: ORG\1_TODOS_ALTERS_ROLLBACK.sql
ORG가 개별 파일인 경우: ORG\1_TABLA_ROLLBACK.sql, ORG\1_PROC_ROLLBACK.sql (다른 번호, MOD와 동기화되지 않음)

CesarChv19/claude-skills_MC

claude-skills_MC란 무엇인가요?

즐겨 사용하는 AI에게 물어보기

문서