shareds

코딩 에이전트에 꽂아 쓰는 지식 샤드예요. 그동안 쌓은 개발 노하우를 스킬과 ESLint 프리셋으로 만들어 뒀어요.

뭐가 들어 있어요 · 스킬 꽂기 · ESLint 쓰기 · Oracle Design · 패키지 · 개발

---

사이버펑크 2077에 '샤드'라는 아이템이 있어요. 칩 하나 꽂으면 다른 사람 지식이 통째로 내 것이 돼요. 이 레포가 딱 그거예요. 테스트, 시각 QA, 시스템 설계, 에이전트 오케스트레이션을 스킬로 만들어 뒀어요. 코딩 에이전트에 꽂으면 바로 써요. 코드 품질 규칙은 ESLint 프리셋으로 따로 빼놨어요.

쌓아둔 개발 지식  ──▶  Claude Code / Codex 스킬  ──▶  설계·구현·검증이 일정해져요
코드 품질 규칙    ──▶  조합형 ESLint 프리셋      ──▶  에디터랑 CI에서 바로 잡아줘요

뭐가 들어 있어요

영역	들어 있는 것	배포
코드 품질	조합형 ESLint 프리셋, 직접 만든 규칙	npm
검증	Oracle 계약, TDD, 행동 테스트, 브라우저·스크린샷	에이전트 플러그인
설계	프론트엔드 시스템 패턴, Figma 제품·랜딩 디자인	에이전트 플러그인
에이전트	워크플로 그래프 설계랑 실행	에이전트 플러그인

스킬 꽂기

Claude Code는 두 줄이면 끝나요.

/plugin marketplace add lodado/shareds
/plugin install vibe-coding-helper@my-vibe-coding-helper

vibe-coding-helper 자리에 원하는 플러그인 이름을 넣으면 돼요.

vibe-coding-helper
frontend-oracle-design
agent-graph-engineering
frontend-system-design
test
frontend-visual-qa
frontend-interface-design
ux-flow-diagram
agent-memory

패키지 안에 .claude-plugin/plugin.json이랑 .codex-plugin/plugin.json이 같이 들어 있어요. 둘 다 같은 skills/ 디렉터리를 읽어요. 스킬 하나 만들면 두 에이전트가 같이 써요.

UX Flow Diagram

ux-flow-diagram runs only when explicitly invoked as $ux-flow-diagram. It reads Figma Prototype reactions, bounded codebase traces, requirements, or an existing Flow IR and produces evidence-aware JSON, Markdown, and Mermaid. Ordinary design or coding requests do not activate it. It never modifies Prototype connections; FigJam export requires a separate explicit request.

The Figma design skill separately creates approved Prototype connections while building interactive designs and verifies them by reading the reactions back.

ESLint 쓰기

설정 기준: 2026-09-18

base 프리셋을 깔고, 그 위에 필요한 것만 얹으면 돼요.

// eslint.config.mjs
import base from '@lodado/eslint-config'
import react from '@lodado/eslint-config/react'
import a11y from '@lodado/eslint-config/a11y'
import quality from '@lodado/eslint-config/quality'
import localRules from '@lodado/eslint-config/local-rules'

export default [...base, ...react, ...a11y, ...quality, ...localRules]

쓸 수 있는 프리셋이에요.

.(base) react next a11y turbo local-rules testing query quality fsd strict-types functional interaction

플러그인은 패키지 의존성으로 함께 설치되지만, 규칙은 해당 프리셋을 import해야 켜져요.

• base: disable 사유·규칙명을 요구하고, 사용하지 않는 disable을 오류로 잡아요.
• react: effect 오용 검사에 더해 purity·immutability·refs·static-components와 exhaustive-deps를 오류로 검사해요. 리스너·fetch·observer·타이머 누수는 경고해요.
• strict-types: 처리하지 않은 Promise, Promise 오용, any의 전파, 불필요한 조건, 누락된 union 분기를 타입 정보로 검사해요.
• functional: domain/, selectors/, reducers/ 아래 TypeScript와 *.pure.ts 계산 코드의 변경·I/O·시간/난수 접근을 제한해요. 테스트는 제외하며 .mts·.cts도 지원해요.

strict-types와 functional은 tsconfig가 필요하고 선택해서 추가해요. Next.js에서는 base → next → react 순서로 합쳐 React의 엄격한 규칙을 유지해요. 순수 영역 밖의 I/O·React 코드까지 금지하지 않으며, ESLint가 완전한 순수성을 증명하지는 않아요.

더 자세한 건 여기 있어요.

• 설정 방법: eslint-setup 스킬
• quality가 AI 코드에서 뭘 막는지: SonarJS AI quality 규칙

npm 배포는 아직이에요. 지금은 이 레포를 워크스페이스로 가져다 쓰면 돼요.

Oracle Design 자세히

frontend-oracle-design은 이 레포에서 제일 큰 스킬이에요. 한 줄로 말하면 구현 생성기가 아니라 검증 하네스예요.

에이전트한테 기능을 시키면 보통 이래요. 애매한 부분을 자기 마음대로 정해요. 테스트는 통과했다고 하는데 뭘 통과했는지 몰라요. 나중에 보면 요구사항이 슬쩍 바뀌어 있어요.

Oracle은 그걸 막아요. 정하지 않은 정책은 정하기 전까진 진행 안 해요. 승인된 계약은 파일로 잠그고, 실행 결과는 전부 원장에 남겨요.

어떻게 도나요

  요청
   │
   ├─ Low ──▶ low-fast-path: 기존 레포 검증만
   │
   └─ Medium / High
          │
          ▼
      ① DEFINE     Outcome Brief·Source Registry·계약 행 작성 + 사용자 확인
          │
          ▼
      ② LOCK       승인한 카드와 정책 출처의 내용 지문 고정
          │
          ▼
      ③ PROVE      VALID_RED로 기능 부족 때문에 실패하는지 증명
          │
          ▼
      ④ BUILD      최소 구현, GREEN, 실행 증거와 ledger 기록
          │
          ▼
      ⑤ REVIEW     표준은 독립 리뷰 1명, High-risk는 독립 리뷰 2명과 join
          │
          ▼
      ⑥ CERTIFY    lock·증거·review receipt를 재검사해 REVIEW_VERIFIED

  옆 출구
  POLICY_GAP                   ──▶ 사람의 정책 결정 대기
  PRODUCT_DEFECT               ──▶ BUILD
  EVIDENCE_GAP/HARNESS_DEFECT  ──▶ 증거만 보정한 뒤 BUILD
  FAIL                         ──▶ 장부 전/후를 구분해 정지

이건 사람이 읽는 6단계 운영 화면이에요. 실제 Controller는 사용자 승인, 실패 증명과 구현, 시각 증거 대기, 표준/High-risk 리뷰, 장부 전후 정지를 별도 Node로 유지해요. 정확한 Node·Edge·fallback·terminal 수와 전체 그래프는 패키지 README가 원본 JSON에서 자동으로 생성합니다.

핵심 규칙 몇 개

• 정책 출처는 승인된 문서예요. 기존 코드나 현재 브라우저 동작은 증거일 뿐 근거가 아니에요
• 카드 승인 전에는 production 코드를 못 건드려요
• 정책이 바뀌면 잠긴 파일을 고치는 게 아니라 새 revision을 만들어요
• assertion 약화, test.skip, 임의 sleep은 금지예요
• 보고할 때 말로 풀지 않고 runId를 인용해요

끝나는 상태

상태	뜻
ORACLE_READY	카드 잠갔어요. 구현 들어가도 돼요
IMPLEMENTED_GREEN	구현 검증은 통과했지만 시각 증거 대기면 여기서 재개해요. 최종 완료는 아니에요
REVIEW_VERIFIED	리뷰 finding까지 반영하고 재통과했어요
NEEDS_DECISION	결과를 바꾸는 정책이 미결이에요. 질문을 뱉어요
FAIL	환경·하네스 문제나 예산 소진으로 판정 불가예요

무한 루프 방지

피드백은 원인별로 나눠서 예산을 써요. 예산 다 쓰면 BUDGET_EXHAUSTED로 멈춰요.

분류	예산	처리
POLICY_GAP	2	질문 출력하고 NEEDS_DECISION
HARNESS_DEFECT	2	테스트 하네스만 보정해요
PRODUCT_DEFECT	3	VALID_RED 뒤에 구현을 고쳐요
EVIDENCE_GAP	-	잠긴 범위 안에서 매핑을 채워요
ENVIRONMENT_DEFECT	-	production 안 건드리고 FAIL
NON_ORACLE_OPINION	-	기록만 하고 완료를 막지 않아요

딸린 스크립트

판정은 말이 아니라 스크립트가 해요.

oracle-verify.mjs   card | red | evidence | findings | review | scan
oracle-lock.mjs     create | verify
oracle-run.mjs      init | status | exec | transition | budget | review-packet | review-brief
generate-workflow-docs.mjs       README 그래프 요약 생성 | --check

review-brief는 현재 리뷰 근거에서 사용자 목표·차단 항목·미완료 증거·비차단 의견을 모은 읽기 전용 요약입니다. 원본 카드·리뷰 입력이나 승인 절차를 대체하지 않습니다.

혼자 다 하지는 않아요. 테스트 작성·판정은 test, 스크린샷이랑 브라우저는 frontend-visual-qa, 기능별 구현 선택지는 frontend-system-design이 가져가요.

자세한 건 스킬 문서에 있어요.

패키지

npm으로 나갈 것들이에요.

패키지	설명
@lodado/eslint-config	필요한 것만 켜는 조합형 프리셋
@lodado/eslint-plugin-local-rules	여러 프로젝트에서 같이 쓰는 규칙

에이전트에 꽂는 플러그인이에요.

플러그인	설명
vibe-coding-helper	ESLint 도입이랑 레포 컨벤션
frontend-oracle-design	위험도 기반 Oracle 계약, TDD, 근거, 리뷰
agent-graph-engineering	에이전트 워크플로 그래프 설계랑 실행
frontend-system-design	잘 알려진 프론트엔드 문제의 설계 패턴
test	Oracle 기반 결정론적 행동 테스트
frontend-visual-qa	스크린샷 비교랑 직접 브라우저 QA
frontend-interface-design	$reference-driven-figma-design: HCI·레퍼런스 비교 → 러프 와이어프레임 설명 → 편집 가능 Figma 디자인

개발

pnpm 워크스페이스랑 Turborepo로 굴러가요.

pnpm install
pnpm lint
pnpm test
pnpm changeset

main이랑 dev에 push하거나 PR 올리면 lint랑 test가 돌아요. npm 릴리스는 조건이 두 개예요. 레포 변수 ENABLE_NPM_RELEASE가 true여야 하고, @lodado/*를 배포할 수 있는 NPM_TOKEN이 있어야 해요.

라이선스

MIT © lodado

Blog Voice Cloner

blog-voice-cloner는 한국어·영어 블로그 문체를 근거와 함께 분석하고, 작성자별 기간 프로필을 저장하며, 새 내용에 문체를 적용하는 스킬입니다. 원문 내용과 작성 내용을 분리하고 의미·중복·과잉 모방을 검토합니다. Python 3.10+ 표준 라이브러리 기반이며 웹 수집은 호스트 도구로 수행합니다.

Agent Memory

Agent Memory 패키지는 recall → 작업 → log → 선택적 TIL/generalize → 검토된 규칙 승격 루프를 제공합니다. 6개 스킬을 Claude, Codex, jcode, Cursor, 공용 .agents 경로에 설치할 수 있습니다. 기존 Vault를 재배치하거나 규칙을 자동 승격하지 않습니다.