TypeScript / JavaScript 가이드

Kiro로 TypeScript/JavaScript 프로젝트를 작성·디버그·유지보수하기 위한 권장 환경 구성과 활용 패턴을 정리합니다.

사전 준비

Kiro의 AI 기능을 가장 매끄럽게 쓰려면 아래 도구가 미리 설치되어 있어야 합니다. 버전은 가급적 최신 LTS 또는 안정 버전을 권장합니다.

• Node.js — 런타임 (LTS 권장)
• TypeScript — 전역 또는 프로젝트 로컬 설치
• Package Manager — npm, pnpm, yarn 중 택일
• Git — 버전 관리

추천 확장

Kiro는 Open VSX 호환 확장을 그대로 사용할 수 있습니다. JS/TS 작업에는 다음을 권장합니다.

• ESLint — 린팅과 코드 품질 점검
• Prettier - Code Formatter — 일관된 자동 포매팅
• Auto Rename Tag — HTML/JSX 짝 태그 동시 리네이밍
• JavaScript (ES6) code snippets — 자주 쓰는 ES6 스니펫

프로젝트 환경 다루기

설정과 구조 잡기

Kiro에게 자연어로 지시하여 초기 설정을 빠르게 끝낼 수 있습니다. 예를 들어 다음과 같은 프롬프트가 잘 작동합니다.

• “React + TypeScript 프로젝트용 tsconfig.json을 strict 옵션 위주로 만들어 줘.”
• “기존 ESLint 설정을 flat config로 전환해 줘.”
• “pnpm workspace 기반 monorepo 구조를 제안하고 폴더 트리를 만들어 줘.”

코드 분석과 리팩터링

1. Code Quality Analysis — 잠재 버그, 성능 이슈, 스타일 위반을 한 번에 검토합니다.
2. Refactoring Assistance — 함수 추출, 이름 변경, 모듈 재구성 등 구조 개선을 도와줍니다.
3. Type Inference — 순수 JS 코드에서 적절한 TS 타입을 제안받아 점진적으로 마이그레이션할 수 있습니다.

예시: “이 함수에서 의심되는 버그를 찾아 줘”, “Promise 체인을 async/await으로 바꿔 줘”, “이 모듈을 .ts로 변환하고 타입을 채워 줘.”

디버깅 보조

스택 트레이스나 컴파일러 에러를 그대로 붙여 넣으면 평이한 한국어로 원인을 설명하고 수정안을 제시합니다. 예를 들어 TS2339: Property 'value' does not exist on type 'never' 같은 메시지도 어떤 추론 흐름에서 never가 만들어졌는지까지 짚어 줍니다.

Steering으로 프로젝트 맥락 주입

Steering은 모든 대화에 자동으로 함께 전달되는 프로젝트 전용 컨텍스트입니다. 기본적으로 세 개의 파일이 제공됩니다.

1. product.md — 제품 개요
2. tech.md — 기술 스택
3. structure.md — 디렉터리/모듈 구조

커스텀 Steering 파일 만들기

1. 사이드바의 Kiro 뷰를 엽니다.
2. Agent Steering 섹션에서 + 버튼을 클릭합니다.
3. 주제를 명확히 알 수 있는 파일명을 입력합니다(예: js-conventions.md).
4. 마크다운으로 규칙·패턴·예시를 작성합니다.

저장된 파일은 .kiro/steering/ 아래에 위치합니다.

코드 스타일 컨벤션 예시

• 네이밍: 변수/함수는 camelCase, 클래스·React 컴포넌트는 PascalCase, 상수는 UPPER_SNAKE_CASE.
• 파일 구조: 컴포넌트당 한 파일, 도메인별 폴더 그룹화, 공개 API는 index.ts에서 재노출.
• TypeScript: interface 우선, 명시적 반환 타입, any 사용 자제.

프레임워크 가이드라인 예시

• 컴포넌트: 함수형 + Hooks, container/presentational 분리.
• 상태 관리: 전역은 React Context, 로컬은 useState, 복잡한 전이는 useReducer.
• 성능: useMemo, React.memo, useCallback을 측정 후 선택적 적용.

Agent Hooks로 작업 자동화

Agent Hooks 섹션에서 +를 누르고 자연어로 워크플로를 정의하면, 저장 등 특정 이벤트에 맞춰 Agent가 자동 실행됩니다. 자주 쓰이는 예시는 다음과 같습니다.

• Test Generation Hook — 파일 저장 시 Jest 테스트 자동 생성.
• Type Checking Hook — 백그라운드 TS 타입 검사.
• Dependency Update Hook — 오래된 npm 패키지 점검.
• ESLint Auto-fix Hook — 저장 시 eslint --fix 실행 후 남은 이슈 보고.
• Component Documentation Hook — props 인터페이스를 추출해 README.md와 사용 예시까지 갱신.

MCP 서버 활용

프런트엔드 작업에는 AWS Labs의 Frontend MCP Server를 연결하면 디자인 시스템·React 패턴 관련 정보를 바로 끌어올 수 있습니다.

{
  "mcpServers": {
    "frontend": {
      "command": "uvx",
      "args": ["awslabs.frontend-mcp-server@latest"],
      "env": {
        "FASTMCP_LOG_LEVEL": "ERROR"
      }
    }
  }
}

더 많은 서버 카탈로그는 AWS MCP Servers와 Awesome MCP Servers 목록에서 찾을 수 있습니다.

#docs로 공식 문서 참조

채팅에서 #docs를 입력하면 주요 런타임·프레임워크 문서를 바로 컨텍스트에 끌어올 수 있습니다. 사용 가능한 키워드 예: #Node.js, #TypeScript, #React, #Svelte, #Express, #Vue.js, #Alpine.js. 특정 문서가 필요하면 #URL 형태로 직접 지정할 수도 있습니다.

오류를 빠르게 잡는 세 가지 경로

1. Inline Chat — 코드 위에서 Cmd/Ctrl + I로 즉석 대화.
2. Add to Chat — Cmd/Ctrl + L로 선택 영역을 채팅에 추가.
3. Quick Fix — 에러/경고에 마우스를 올린 뒤 Quick fix → Ask Kiro 선택.

참고 자료

• TypeScript 공식 문서 — typescriptlang.org/docs/
• JavaScript MDN Web Docs — developer.mozilla.org/en-US/docs/Web/JavaScript
• Node.js 공식 문서 — nodejs.org/en/docs/