EugineKosenko/majordom

create-cmpnnt

새로운 컴포넌트 (cmpnnt) — 명령어, 프로시저, 서브커맨드, Yew-컴포넌트 또는 완전한 크레이트 — 를 리터러레이트 org-babel 스타일로 생성하는 스킬입니다. 이 스타일은 ~/.claude/CLAUDE.md에 문서화되어 있습니다. 실제 code/ads-back (crates/api/create-card.org, crates/api/retrve-card.org, crates/cli/main.org, crates/svc/main.org, 루트 config.org, env.org) 파일을 기반으로 합니다.

단계 0 — 변형 결정

기본값(명시적 인수 없음)으로 사용자의 요청 자체에서 변형을 결정하십시오. 모호한 경우, 조용히 추측하지 말고 AskUserQuestion을 통해 명확히 하는 질문을 하나 하십시오:

• A. 기존 크레이트 내 프로시저/명령어 — 일반적인 경우(예: crates/api의 새 rocket-핸들러, crates/db의 새 라이브러리 함수). 하나의 새 org 파일, config.org는 변경하지 않음.
• B. 기존 CLI의 서브커맨드 — 새 파일 <서브커맨드>.org (모드) + 해당 크레이트의 기존 main.org에 추가 (mod, Command:Елементи, Варіанти).
• C. Yew-컴포넌트 (ads-front) — crates/app/marker.org와 유사한 구조: "속성" 섹션에 컴포넌트 속성, Html 블록. 동일한 프레임워크(선언 전 정의, 개념당 하나의 헤딩), 다른 블록 용어.
• D. 새 크레이트 ("연합 cargo") — 컴포넌트가 논리적으로 기존 크레이트에 맞지 않을 때. 이 경우 컴포넌트 자체 외에도 새 크레이트의 config.org, env.org, main.org와 루트 config.org에 등록이 필요합니다(4단계 참조).

변형 D를 "만약을 위해" 지정하지 마십시오 — 사용자가 명시적으로 새 크레이트를 요청하거나, 기존 크레이트가 논리적으로 적합하지 않은 경우(그리고 사용자가 확인한 경우)에만 지정하십시오.

단계 1 — org 파일 언어

언어는 상황에 따라 다르며 고정되어 있지 않습니다. 파일을 생성하기 전에 대상 디렉토리(code/ads-back/env.org — 영어, 대부분의 crates/api/*.org — 우크라이나어)에서 인접한 org 파일들의 언어를 확인하십시오: 디렉토리에 명확한 다수 언어가 있으면 같은 언어로 작성하고, 새 디렉토리이거나 인접 파일의 언어가 모호하면 사용자에게 하나의 질문으로 물어보고 추측하지 마십시오.

단계 2 — 공통 프레임워크 (모든 변형)

변형에 관계없이, 각 새 org 파일은 자체 :tangle 타겟을 가집니다:

1. #+title: ... — 컴포넌트 이름(1단계의 언어로).

2. 필요한 경우 — 명세에 대한 링크가 있는 단락 ([[https://...][специфікацію]]), create-card.org에서처럼.

3. 첫 번째 헤딩 (* Модуль / * Файл / * Крейт — 같은 디렉토리의 인접 파일 예를 따라; 엄격히 고정되지 않음)과 스켈레톤 블록:

   #+begin_src rust :noweb yes :mkdirp yes :tangle src/ИМЯ_ФАЙЛА.rs
     <<Декларації>>
   
     <<Визначення>>
   #+end_src
   

4. 스켈레톤 바로 다음 — * Виконавець 섹션(프로시저/명령어의 경우)과 두 개의 블록: :noweb-ref Декларації (임포트, ads_api의 Request/Response 타입 포함) 및 :noweb-ref Визначення (함수 pub fn run(...) 자체, 본문은 대부분 <<Дії>>를 db::cnnctn().transaction(...) 내부에 포함, 트랜잭션이 필요한 경우).

5. 각 후속 논리적 세부 사항(검증, 필드 가져오기, 테이블 삽입 등) — 별도의 */** 헤딩과 자체 :noweb-ref Декларації(새 use가 필요한 경우) 및 :noweb-ref Дії — 이 순서로 (선언 후 사용, 다른 곳과 마찬가지). 모든 논리를 하나의 블록에 모으지 마십시오 — 각 의미 있는 단계는 create-card.org(하나의 프로시저에 15개 이상의 개별 헤딩)에서처럼 자체 헤딩을 가져야 합니다.

6. 한 단계가 도우미 함수(예: create-card.org의 upsert_phone)를 생성하면, 함수 시그니처를 위한 자체 :noweb-ref Визначення와 본문을 위한 자체 명명된 noweb-ref (upsert-phone:Дії) 및 그 내부의 각 동작에 대한 하위 헤딩 **/***를 사용합니다.

B 변형 (CLI 서브커맨드)은 새 스켈레톤 블록이 없다는 점에서 다릅니다 — 대신 기존 main.org에 새 헤딩-스켈레톤 없이 세 개의 noweb 블록을 추가합니다: :noweb-ref Декларації (mod нова_підкоманда;), :noweb-sep ",\n" :noweb-ref Command:Елементи (Command 열거형 변형과 인수 필드), 및 :noweb yes :noweb-sep ",\n" :noweb-ref Варіанти (Command::Варіант { ... } => crate::модуль::run(...)) — 각각은 동작 이름의 *-헤딩(예: * Створення організації)에 있으며, 구현 자체는 공통 프레임워크(2단계, 변형 A)에 따라 별도의 새 서브커맨드 org 파일에 있습니다.

C 변형 (Yew 컴포넌트)은 섹션 이름이 다릅니다: "Виконавець" 대신 "Властивості" 섹션 (struct ...Props, 각 속성은 하나의 **-하위 섹션, :noweb-sep ",\n" :noweb-ref ІмʼяProps:Властивості), 그리고 "Компонент" 섹션 (#[function_component(...)], 본문은 <<Ім'я:Стан>>, <<Ім'я:Ефекти>>, <<Ім'я:Обробники>>, html! { <<Ім'я:Html>> }). 이 변형의 실제 예로 code/ads-front/crates/app/marker.org를 참조하십시오.

단계 3 — 기본적인 main 함수 (변형 D, 먼저)

새 크레이트의 main.org 첫 번째 버전은 가장 단순해야 합니다 — 오류 처리 없이, Result 없이, async 없이, 로거/env 초기화 없이, 구체적인 필요가 있을 때까지:

#+title: КРЕЙТА ИМЯ

* Файл

#+begin_src rust :noweb yes :mkdirp yes :tangle src/main.rs
  <<Декларації>>

  <<Визначення>>

  fn main() {
      <<Дії>>
  }
#+end_src

<<Дії>>는 처음에는 완전히 비어 있을 수 있습니다 (새 크레이트는 아직 아무 작업도 하지 않음) — 이는 정상적인 첫 번째 단계이며, 이후 헤딩이 crates/cli/main.org/crates/svc/main.org에서처럼 점차 채워집니다. 오류 처리 (Result, ?), async, dotenv/env_logger 초기화 등은 구체적인 단계에서 실제로 필요할 때 별도의 헤딩으로 나중에 추가하십시오 — 미리 추가하지 마십시오.

단계 4 — 새 크레이트: config.org 및 연합 config.org에 등록

1. crates/ИМЯ/config.org — 크레이트 파일 (crates/cli/config.org를 예로 참조):

   #+title: =Cargo=-файл
   
   * Файл
   
   #+begin_src toml :noweb yes :tangle Cargo.toml
     [package]
     name = "ИМЯ"
     version = "0.1.0"
     edition = "2021"
   
     [dependencies]
     <<Залежності>>
   #+end_src
   

   각 의존성은 별도의 * =크레이트_이름= 헤딩과 :noweb-ref Залежності (이름 = { workspace = true })이며, CLAUDE.md의 규칙에 따라 정렬됩니다 (서드파티 → forge → 프로젝트 크레이트, 그렇지 않으면 알파벳 순). * Версія =Rust=/* Локальна конфігурація (rust-toolchain.toml/.cargo/config.toml) 블록은 이 디렉토리에서 이미 그렇게 하는 것이 관례인 경우에만 인접한 config.org에서 복사하십시오 — 인접한 크레이트가 그렇게 하지 않으면 "만약을 위해" 추가하지 마십시오. 복사하는 경우 파일은 다중 타겟(여러 다른 :tangle)이 되며, 모든 noweb 블록(Залежності 포함)은 접두사가 붙은 이름(Cargo:Залежності, config:Визначення 등, CLAUDE.md 참조)을 사용합니다 — 아래 루트 config.org에서처럼.

2. 루트 config.org (워크스페이스)에 새 * =ИМЯ= 헤딩을 추가하고, 루트의 * =db=/* =api= 섹션 패턴에 따라 두 개의 블록을 포함합니다:

   #+begin_src toml :noweb-sep ",\n" :noweb-ref Cargo:Крейти
     "crates/ИМЯ"
   #+end_src
   
   #+begin_src toml :noweb-ref Cargo:Залежності
     ИМЯ = { path = "crates/ИМЯ" }
   #+end_src
   

3. env.org — 새 크레이트가 자체 환경 변수를 도입하지 않으면 아무것도 건드리지 마십시오. 도입하는 경우, 그리고 프로젝트에 이미 공유 루트 env.org가 있으면 거기에 새 *-섹션을 자체 :noweb-ref(예: * Database access/* =JWT= parameters)로 추가하고 별도 파일을 생성하지 마십시오. 새 크레이트를 위한 별도의 env.org는 해당 크레이트가 독립적인 배포(자체 .env, 동일한 프로세스가 아님)이고 공유 env.org가 없는 경우에만 생성하십시오. 어떤 경우든 첫 번째 env.org는 구체적인 변수 없이 완전히 비워둘 수 있습니다 (можна взагалі без значень, тільки головний файл) — 단지 스켈레톤:

   #+title: =dotenv= file
   
   * Configuration file
   
   #+begin_src conf :noweb yes :tangle .env.example
     <<Визначення>>
   #+end_src
   

   그리고 실제 변수가 생기면 나중에 구체적인 * =Х= parameters-섹션으로 채웁니다.

단계 5 — 각 변경 후 확인

각 중요한 org 소스 편집 후:

1. emacsclient --eval을 통한 실제 tangle (.rs/.toml/.env.example의 내용을 수동으로 절대 작성하지 마십시오 — 해당 전역 규칙 참조).
2. cargo check -p КРЕЙТ (ads-front의 경우 --target wasm32-unknown-unknown 추가) — 경고 및 오류 없음.
3. 변경된 파일에 org-lint 스킬을 실행하고 "확실한" 발견 사항은 즉시 수정하고, "확인 필요"는 검토합니다.
4. 방금 작성/변경된 산문의 경우 — 동일한 emacsclient를 통해 (font-lock-ensure) + org-fill-paragraph를 실행하고 수동으로 하지 않습니다.

네 가지 항목이 각 새 파일 또는 변경된 org 파일에 대해 완료될 때까지 사용자에게 컴포넌트를 준비된 것으로 표시하지 마십시오.