feat: structure knowledge base with P-Reinforce categories and include Skybound wiki Batch 11.01-B
This commit is contained in:
@@ -0,0 +1,26 @@
|
||||
---
|
||||
title: 웹 접근성 및 포용적 설계 (a11y)
|
||||
category: Software Architecture
|
||||
tags: [Accessibility, a11y, Semantic HTML, Inclusivity]
|
||||
created: 2026-04-20
|
||||
---
|
||||
|
||||
# [[Accessibility_Inclusivity]] (포용적 설계와 접근성)
|
||||
|
||||
## 📌 한 줄 통찰 (The Karpathy Summary)
|
||||
> 웹은 '모두'를 위한 공간이어야 한다. 신체적 제약이 시스템 이용의 제약이 되지 않게 하는 것은 '매너'가 아니라 전문 개발자의 '책임'이다.
|
||||
|
||||
## 📖 구조화된 지식 (Synthesized Content)
|
||||
- **Semantic HTML (의미론적 태그)**:
|
||||
- `<div>`로만 도배하지 마라. `<main>`, `<article>`, `<section>`, `<nav>` 등 의미가 담긴 태그를 써야 기계(스크린 리더)와 검색 엔진이 내 콘텐츠의 중요도를 파악한다.
|
||||
- **ARIA & States**:
|
||||
- 표준 HTML로 설명이 불가능한 인터랙션(예: 커스텀 탭 메뉴)은 `aria-label`, `aria-hidden` 등을 통해 기계에게 보조 설명을 전한다.
|
||||
- **Keyboard Navigation**:
|
||||
- 마우스 없이 `Tab` 키와 `Enter` 키만으로 내 앱의 모든 핵심 기능을 수행할 수 있는지 검증하라. 포커스링을 숨기지 마라. 누군가에게는 유일한 가이드라인이다.
|
||||
|
||||
## ⚠️ 모순 및 업데이트 (RL Update)
|
||||
- 접근성을 챙기는 것은 단순히 윤리적인 문제를 넘어, **SEO(검색 노출)** 성적과 직결된다. 구글 검색 로봇은 눈이 없기에, 스크린 리더와 유사한 방식으로 우리 사이트를 평가하기 때문이다.
|
||||
|
||||
## 🔗 지식 연결 (Graph)
|
||||
- Related: [[Styling_Governance]] , [[React_Clean_Code_Best_Practices]]
|
||||
- Ethic: [[Collaboration_Governance]]
|
||||
@@ -0,0 +1,26 @@
|
||||
---
|
||||
title: 협업 가이드라인 및 코드 거버넌스
|
||||
category: Software Architecture
|
||||
tags: [Collaboration, PR, Code Review, Documentation, Governance]
|
||||
created: 2026-04-20
|
||||
---
|
||||
|
||||
# [[Collaboration_Governance]] (협업과 코드 품격)
|
||||
|
||||
## 📌 한 줄 통찰 (The Karpathy Summary)
|
||||
> 코드는 혼자 쓰는 일기장이 아니라 함께 짓는 건축물이다. 동료의 시간을 아껴주는 문서화와 소통 방식이 당신의 가치를 증명한다.
|
||||
|
||||
## 📖 구조화된 지식 (Synthesized Content)
|
||||
- **Pull Request (PR) 에티켓**:
|
||||
- "이거 고쳤습니다"는 최악의 PR이다. 무엇을(What), 왜(Why), 어떻게(How) 했는지 명시하고 가능한 시각적 결과물(스크린샷, GIF)을 첨부하여 리뷰어의 인지 부하를 줄여라.
|
||||
- **Code Review Protocol**:
|
||||
- P1(필수 반영), P2(권장), P3(질문/의견) 식으로 중요도를 표시하라. 비판은 날카롭게 하되 표현은 따뜻하게 하여 팀의 심리적 안정성을 유지하라.
|
||||
- **The Living Document**:
|
||||
- 복잡한 비즈니스 로직이나 기묘한 버그 픽스는 반드시 주석이나 README에 '의도'를 남겨라. 주석은 '무엇을 하는지'가 아니라 '왜 이렇게 했는지'를 적는 곳이다.
|
||||
|
||||
## ⚠️ 모순 및 업데이트 (RL Update)
|
||||
- 완벽한 거버넌스를 추구하느라 소통이 무거워지면 안 된다. 빠른 배포가 필요한 시점에는 '기술 부채'를 명문화하고 나중에 갚는 기민함(Agile)도 필요하다.
|
||||
|
||||
## 🔗 지식 연결 (Graph)
|
||||
- Related: [[React_Clean_Code_Best_Practices]] , [[Deployment_Final_Gate]]
|
||||
- Foundation: [[System_Debugging_Protocol]]
|
||||
@@ -0,0 +1,28 @@
|
||||
---
|
||||
title: 애플리케이션 안정성 및 로깅 (Error Boundary)
|
||||
category: Software Architecture
|
||||
tags: [Reliability, Error Boundary, Sentry, Logging, Stability]
|
||||
created: 2026-04-20
|
||||
---
|
||||
|
||||
# [[Reliability_Safety_First]] (애플리케이션 안정성)
|
||||
|
||||
## 📌 한 줄 통찰 (The Karpathy Summary)
|
||||
> 에러는 막는 것이 아니라 '우아하게 격리'하는 것이다. 컴포넌트 하나가 무너져도 전체 시스템은 안전하게 순항해야 한다.
|
||||
|
||||
## 📖 구조화된 지식 (Synthesized Content)
|
||||
- **Error Boundary (에러 바운더리)**:
|
||||
- 리액트의 `componentDidCatch` 생명 주기를 활용하여, 특정 하위 컴포넌트 트리의 런타임 에러를 포착하고 '대체 UI'를 보여주는 최후의 방어선이다.
|
||||
- **적용 전략**: 전체 앱을 감싸는 전역 바운더리 외에도, 독립적으로 동작하는 위젯(예: 사이드바, 게시글 목록) 단위로 세밀하게 감싸는 것이 유리하다.
|
||||
- **Observability (로깅 및 관측 가능성)**:
|
||||
- **Sentry 연동**: 클라이언트 사이드에서 발생하는 에러를 스택 트레이스와 함께 실시간 수집하여, 사용자가 제보하기 전에 개발자가 먼저 인지하게 한다.
|
||||
- **Contextual Logging**: 에러 발생 시 사용자의 브라우저 버전, 마지막 행동(Breadcrumbs)을 함께 기록하여 재현 가능성을 높인다.
|
||||
- **Graceful Fallback**:
|
||||
- 에러 발생 시 단순한 "에러 발생" 문구보다는 "일시적인 오류입니다. [다시 시도하기]" 버튼을 제공하여 사용자 경험 단절을 최소화한다.
|
||||
|
||||
## ⚠️ 모순 및 업데이트 (RL Update)
|
||||
- 모든 곳에 에러 바운더리를 칠 필요는 없다. 데이터와 UI가 1:1로 매칭되는 구조라면 차라리 상위에서 에러를 처리하는 것이 논리적으로 명확할 수 있다.
|
||||
|
||||
## 🔗 지식 연결 (Graph)
|
||||
- Related: [[System_Debugging_Protocol]] , [[React_Testing_Strategy]]
|
||||
- Foundation: [[System_Protocol_Standard]]
|
||||
@@ -0,0 +1,27 @@
|
||||
---
|
||||
title: 스타일 거버넌스 및 디자인 시스템
|
||||
category: Software Architecture
|
||||
tags: [Styling, Tailwind, CSS-in-JS, Design System, Responsive]
|
||||
created: 2026-04-20
|
||||
---
|
||||
|
||||
# [[Styling_Governance]] (스타일 매니지먼트)
|
||||
|
||||
## 📌 한 줄 통찰 (The Karpathy Summary)
|
||||
> 디자인은 '예쁜 픽셀'이 아니라 '일관된 약속'이다. 단 하나의 변수가 바뀌었을 때 전체 앱의 조화가 유지되는 구조가 진짜 디자인 시스템이다.
|
||||
|
||||
## 📖 구조화된 지식 (Synthesized Content)
|
||||
- **Design Tokens (디자인 토큰)**:
|
||||
- 색상(#FF0000 -> `brand-primary`), 여백(16px -> `spacing-md`)을 추상화된 이름으로 정의하라. 그래야 브랜드 리뉴얼 시 코드 한 줄로 대응 가능하다.
|
||||
- **Utility-First vs Runtime Style**:
|
||||
- **Tailwind CSS**: 클래스명으로 스타일을 정의하여 런타임 오버헤드가 없고 개발 속도가 압도적이다.
|
||||
- **Styled-components**: 컴포넌트 중심의 의미론적 스타일링과 동적 Props 처리에 강점이 있다.
|
||||
- **Mobile First Responsive**:
|
||||
- 작은 화면부터 디자인을 시작하여 넓은 화면으로 확장하라. 이것이 CSS 코드를 30% 이상 줄이는 지름길이다.
|
||||
|
||||
## ⚠️ 모순 및 업데이트 (RL Update)
|
||||
- 과도한 '공통 컴포넌트'화는 오히려 독이 될 수 있다. 버튼 하나에 옵션이 20개가 달리는 순간, 그 버튼은 유지보수의 재앙이 된다. 적절한 '복제'와 '분리'의 균형을 유지하라.
|
||||
|
||||
## 🔗 지식 연결 (Graph)
|
||||
- Related: [[Component_Design_Patterns]] , [[Accessibility_Inclusivity]]
|
||||
- Best Practice: [[React_Clean_Code_Best_Practices]]
|
||||
@@ -0,0 +1,27 @@
|
||||
---
|
||||
title: 단계별 시스템 디버깅 체크리스트 (L1~L3)
|
||||
category: Software Architecture
|
||||
tags: [Debugging, Troubleshooting, Checklist, Process]
|
||||
created: 2026-04-20
|
||||
---
|
||||
|
||||
# 단계별 시스템 디버깅 체크리스트 (The Diagnostic Flowchart)
|
||||
|
||||
## 🔍 L1: 환경 및 무결성 검증 (Low Level)
|
||||
- **대상**: 404 Error, Syntax Error, 파일 경로.
|
||||
- **목표**: **'실행 가능한 물리적 토대'**가 마련되어 있는가?
|
||||
- **필수 조치**: 강제 새로고침(Ctrl + F5), 서버 재시작(Restart Ritual).
|
||||
|
||||
## 🔍 L2: 통신 및 데이터 흐름 검증 (Communication)
|
||||
- **대상**: `onmessage`, `postMessage`, 비동기 처리.
|
||||
- **목표**: 메시지가 의도한 대로 흐르고 있는가?
|
||||
- **필수 조치**: 데이터 흐름 추적(`console.log`), 핸들러 동작 유무 확인.
|
||||
|
||||
## 🔍 L3: 논리 엔진 및 비즈니스 검증 (High Level)
|
||||
- **대상**: 비즈니스 로직, 수학적 공식, 물리 엔진.
|
||||
- **목표**: 코드가 논리적으로 무결한가?
|
||||
- **필수 조치**: 최소 실행 예제(MRE)를 통한 격리 테스트.
|
||||
|
||||
## 🔗 연결된 지식
|
||||
- [[Tetris_Project_Retrospective]]
|
||||
- [[DevOps_Environment_Setup]]
|
||||
@@ -0,0 +1,26 @@
|
||||
---
|
||||
title: 표준 시스템 통신 프로토콜 및 상태 제어
|
||||
category: Software Architecture
|
||||
tags: [Protocol, State Machine, Data Exchange, Lifecycle]
|
||||
created: 2026-04-20
|
||||
---
|
||||
|
||||
# 표준 시스템 통신 프로토콜 및 상태 제어
|
||||
|
||||
## 📡 데이터 교환 규약 (Standard Protocol)
|
||||
모든 컴포넌트 간 통신은 예측 가능한 형태를 유지해야 합니다.
|
||||
- **포맷**: `{ type: 'ACTION_TYPE', payload: { data: value } }`
|
||||
- **주요 액션 타입**:
|
||||
- `INIT`: 시스템 초기화 및 동기화 시작.
|
||||
- `KEY_INPUT`: 사용자 인터랙션 데이터 전송.
|
||||
- `UPDATE`: 엔진 계산 결과의 브로드캐스트.
|
||||
|
||||
## 🔄 시스템 생명 주기 (Life Cycle)
|
||||
시스템은 [초기화 $\rightarrow$ 활성 루프 $\rightarrow$ 종료/정리]의 명확한 단계를 거쳐야 리소스 누수(Memory Leak)를 방지할 수 있습니다.
|
||||
|
||||
## 🚨 상태 머신 (State Machine) 도입
|
||||
시스템 복잡도가 임계치를 넘을 경우, `READY`, `RUNNING`, `PAUSED` 등 상태를 명시적으로 제어하는 **State Machine** 적용을 원칙으로 삼습니다.
|
||||
|
||||
## 🔗 연결된 지식
|
||||
- [[Project_Architecture_Guidelines]]
|
||||
- [[Single_Source_of_Truth]]
|
||||
Reference in New Issue
Block a user