이용 가이드
Getting Started
배포란
코드가 완성되더라도 내 컴퓨터에서만 실행하면 다른 사용자는 이용할 수 없습니다. 프로젝트 형태에 따라 실행 공간, 정보 저장 또는 로그인 기능 중 필요한 요소만 준비합니다. 설치형 프로그램처럼 별도 자원이 필요하지 않은 프로젝트는 스테이션 릴리즈만 진행할 수 있습니다.
프로젝트 공개 흐름
프로젝트 생성 후 필요한 자원만 선택하여 신청하고 스테이션 공개를 진행합니다.
자원과 신청 내역을 통합 관리합니다.
웹 실행이 필요한 경우 신청합니다.
구조화된 정보 저장이 필요한 경우 신청합니다.
사내 계정 로그인이 필요한 경우 신청합니다.
구성원이 프로젝트를 찾고 이용할 수 있도록 공개합니다.
인스턴스, RDB 및 SSO는 선택 사항입니다.
설치형 프로그램처럼 별도 실행 공간이나 데이터베이스가 필요하지 않은 프로젝트는 자원 발급 없이 바로 스테이션 릴리즈를 신청할 수 있습니다.
필요한 자원 선택
프로젝트가 제공하는 기능과 공개 단계에 따라 필요한 자원이 달라집니다.
| 프로젝트의 상황 | 필요한 준비 |
|---|---|
| 로그인·저장·자동 처리가 있는 프로젝트 | 인스턴스를 발급하고 필요에 따라 RDB와 SSO를 연결합니다. |
| 설치형 프로그램 또는 별도 실행 자원이 필요 없는 프로젝트 | 인스턴스 및 RDB 발급 없이 스테이션 릴리즈를 신청합니다. |
| 내 컴퓨터에서만 확인할 프로젝트 | Dev에서 기능을 개발하고 Staging에서 검증한 후 Production으로 전환합니다. |
| 사내 구성원에게 공개할 프로젝트 | 프로젝트 형태에 필요한 준비를 완료한 후 스테이션 릴리즈를 신청합니다. |
작업별 가이드
작업을 선택하면 개념, 준비 항목, 실행 절차 및 완료 결과를 순서대로 확인할 수 있습니다.
| 작업 | 안내 |
|---|---|
| 프로젝트 시작 | 자원과 신청 내역을 관리할 프로젝트를 생성합니다. |
| 인스턴스 발급 | 프로젝트를 지속적으로 실행할 공간을 준비합니다. |
| RDB 발급 | 구조화된 정보를 저장할 공간을 준비합니다. |
| 그룹웨어 SSO 연동 | 사내 계정 로그인 기능을 연결합니다. |
| 스테이션 공개 | 구성원이 프로젝트를 찾고 이용할 수 있도록 공개합니다. |
| 전자 결재·자원 정리 | 신청 상태와 삭제 영향을 확인합니다. |
| 문제 해결 | 배포와 연결 중 자주 발생하는 문제를 확인합니다. |
Starter Kit
Starter Kit
프로젝트의 첫 구조를 잡는
바이브코딩 스타터 키트
코딩 에이전트가 프로젝트의 규칙과 디자인 시스템, 현재 작업 상태를 이해할 수 있도록 구성한 기본 파일과 가이드입니다.
새 프로젝트에 적용하면 작업 기준을 신속하게 설정하고, 세션이 변경되어도 동일한 맥락에서 개발을 이어갈 수 있습니다.
Starter Kit이란
프로젝트의 기능이나 화면을 대신 만드는 코드 템플릿은 아닙니다. 작업 방식, 디자인 기준 및 현재 진행 상태를 문서로 전달하여 새로운 세션에서도 일관된 기준으로 작업할 수 있도록 지원합니다.
사용 전 확인
프로젝트 상태에 따라 적용 방법과 확인해야 할 항목이 달라집니다.
| 확인 항목 | 적용 기준 |
|---|---|
| 새 프로젝트 | 압축을 해제한 파일을 프로젝트 최상위 폴더에 넣고 디자인 시스템을 선택합니다. |
| 기존 프로젝트 | 같은 이름의 파일을 바로 덮어쓰지 않고 기존 규칙과 Starter Kit의 내용을 먼저 비교하여 통합합니다. |
| 디자인 시스템 | 프로젝트 기준에 따라 PlusX 또는 Carbon을 선택합니다. 이미 확정된 디자인 시스템이 있다면 기존 기준을 우선합니다. |
| 민감 정보 | 비밀번호, API 키 및 인증 파일은 지침이나 작업 기록에 입력하지 않습니다. |
Starter Kit은 신규 프로젝트에 적용하는 것을 권장합니다.
기존 프로젝트에 적용할 때는 현재 규칙과 기록이 삭제되지 않도록 파일별 내용을 확인하십시오.
구성 파일
각 파일은 코딩 에이전트의 작업 기준과 세션 간 기록을 구분하여 관리합니다.
| 파일 | 용도 |
|---|---|
| AGENT.md | 코딩 에이전트가 따라야 할 역할, 작업 범위 및 실행 규칙을 정의합니다. |
| AGENT_STATE.md | 현재 진행 상태, 결정 사항 및 다음 작업을 기록합니다. |
| WORKLOG.md | 완료한 작업과 주요 변경 이력을 누적하여 관리합니다. |
| design-kit/ | PlusX와 Carbon 디자인 시스템의 적용 기준을 제공합니다. |
| guides/ | 서비스 구조와 바이브코딩 작업에 필요한 참고 자료를 제공합니다. |
| README.md | Starter Kit의 구성과 기본 적용 방법을 안내합니다. |
적용 절차
다운로드한 파일을 프로젝트에 적용한 후 코딩 에이전트가 지침을 읽도록 요청합니다.
ZIP 파일의 압축을 해제하고 프로젝트 최상위 폴더에 파일을 넣습니다.
AGENT.md에서 PlusX 또는 Carbon 디자인 시스템을 선택합니다.
코딩 에이전트에 “AGENT.md를 읽고 실행해줘.”라고 요청합니다.
세션 종료 전 #end를 입력하여 현재 상태와 작업 내용을 기록합니다.
작업 중 활용
문서의 역할을 구분하여 필요한 시점에 최신 상태로 유지합니다.
| 상황 | 진행 방법 |
|---|---|
| 새 규칙을 결정한 경우 | 코딩 에이전트가 다음 작업부터 동일한 기준을 적용할 수 있도록 AGENT.md에 반영합니다. |
| 현재 상태를 인계해야 하는 경우 | 완료 항목, 진행 중인 항목 및 다음 작업을 AGENT_STATE.md에 정리합니다. |
| 작업을 종료하는 경우 | #end를 입력하여 주요 변경 내용을 WORKLOG.md에 기록합니다. |
| 새 세션을 시작하는 경우 | 코딩 에이전트가 지침과 현재 상태를 먼저 확인하도록 요청한 후 작업을 시작합니다. |
프로젝트 시작
프로젝트란
바이브코딩으로 만든 코드 자체를 저장하는 공간은 아닙니다. 프로젝트 이름과 설명을 기준으로 인스턴스, RDB, SSO, 스테이션 정보 및 전자 결재 기록을 연결하여 관리합니다.
생성 전 확인
프로젝트의 목적과 관리 범위를 명확하게 전달할 수 있는 정보를 준비합니다.
| 준비 항목 | 작성 기준 |
|---|---|
| 프로젝트 이름 | 다른 구성원이 목적을 쉽게 식별할 수 있는 이름을 입력합니다. |
| 한 줄 설명 | 해결하려는 문제와 주요 사용자를 간결하게 작성합니다. |
| 관리 단위 | 하나의 배포 대상에는 하나의 프로젝트 생성을 권장합니다. Dev, Staging 및 Production은 프로젝트 내부에서 구분합니다. |
프로젝트 생성
프로젝트는 별도 전자 결재 없이 즉시 생성됩니다.
내 프로젝트에서 새 프로젝트를 선택합니다.
프로젝트 이름과 한 줄 설명을 입력합니다.
프로젝트 생성을 선택하고 상세 화면으로 이동합니다.
생성 후 진행
프로젝트 형태와 필요한 기능에 따라 다음 작업을 선택합니다.
| 필요한 기능 | 다음 작업 |
|---|---|
| 지속적인 웹 실행 | 인스턴스를 신청합니다. |
| 구조화된 정보 저장 | RDB를 신청합니다. |
| 사내 계정 로그인 | SSO를 신청합니다. |
| 별도 자원이 필요 없는 설치형 프로그램 | 자원 발급 없이 스테이션 릴리즈를 신청합니다. |
자원 발급은 선택 사항입니다.
프로젝트에 필요한 자원만 신청하거나, 별도 자원이 필요하지 않은 경우 바로 스테이션 릴리즈를 진행할 수 있습니다.
인스턴스 발급
인스턴스란
바이브코딩 중에는 내 컴퓨터에서 프로젝트를 실행하지만, 다른 사용자가 언제든 접속하려면 계속 가동되는 실행 공간이 필요합니다. 인스턴스는 서버 기능과 자동 작업을 실행하고 외부 접속에 필요한 도메인과 IP를 제공합니다.
선택 기준
프로젝트가 작동하는 방식에 따라 인스턴스가 필요한지 먼저 확인합니다.
| 프로젝트의 상황 | 권장 방식 |
|---|---|
| 로그인, 정보 저장, 파일 처리 또는 자동 작업이 필요한 경우 | 인스턴스를 신청하여 서버 기능을 계속 실행합니다. |
| 설치형 프로그램처럼 별도 실행 공간이 필요하지 않은 경우 | 인스턴스를 신청하지 않고 스테이션 릴리즈를 진행할 수 있습니다. |
인스턴스는 선택 자원입니다.
설치형 프로그램처럼 별도 실행 공간이 필요하지 않은 프로젝트는 발급하지 않아도 됩니다.
발급 전 확인
신청 화면에서 입력하거나 선택해야 하는 항목을 사전에 준비합니다.
| 준비 항목 | 안내 |
|---|---|
| 환경 | 기능 검증은 Staging, 실제 사용자에게 제공하는 운영 환경은 Production을 선택합니다. |
| 슬러그 | 도메인에 포함할 짧은 영문 이름을 준비합니다. 예: team-book |
| 실행 정보 | 프로젝트 실행 방법과 필요한 환경 변수를 코딩 에이전트와 정리합니다. |
| PostgreSQL 함께 설치 | 규모가 작은 프로젝트에서 간단한 정보 저장이 필요한 경우 선택할 수 있습니다. 별도 RDB가 필요한지는 사전에 확인합니다. |
발급 및 활성화
전자 결재 승인과 발급 활성화는 서로 다른 단계입니다.
프로젝트 상세의 발급 리소스에서 인스턴스로 이동합니다.
환경, 슬러그 및 PostgreSQL 설치 여부를 확인하고 제출합니다.
승인이 완료될 때까지 전자 결재에서 진행 상태를 확인합니다.
발급 활성화를 선택하고 준비가 완료되면 활성 상태를 확인합니다.
활성화 후 확인
발급 카드에서 프로젝트 배포에 필요한 정보를 확인합니다.
| 확인 항목 | 의미 |
|---|---|
| 상태 | 활성으로 표시되면 인스턴스 준비가 완료된 상태입니다. |
| 도메인 | 다른 사용자가 웹 프로젝트에 접속할 때 사용하는 주소입니다. |
| IP | 인스턴스를 식별하고 연결할 때 사용하는 네트워크 주소입니다. |
| PEM 키 | 인스턴스에 안전하게 접속할 때 사용하는 전자 열쇠 파일입니다. |
PEM 키는 활성화 시 한 번만 다운로드할 수 있습니다.
승인된 보안 저장소에 보관하고 Git 저장소, 메신저 또는 이메일에 업로드하지 마십시오. 분실한 파일은 다시 다운로드할 수 없습니다.
RDB 발급
RDB란
회원 이름, 게시글 제목, 예약 날짜처럼 항목이 정해진 정보를 표와 유사한 구조로 정리하여 PostgreSQL에 보관합니다. 프로젝트는 정보를 등록하거나 다시 불러올 때 동일한 환경의 인스턴스를 통해 RDB와 통신합니다.
선택 기준
RDB는 정보를 중앙에서 저장하고 다시 조회해야 하는 경우에만 신청합니다.
| 프로젝트의 상황 | 권장 방식 |
|---|---|
| 사용자가 입력한 정보를 저장하고 검색하거나 수정해야 하는 경우 | 별도 RDB를 신청하여 정보를 구조적으로 관리합니다. |
| 규모가 작고 인스턴스에 PostgreSQL을 함께 설치한 경우 | 내장 PostgreSQL로 충분한지 먼저 확인합니다. |
| 정적 화면만 제공하거나 정보를 저장하지 않는 경우 | RDB를 신청하지 않아도 됩니다. |
RDB는 선택 자원입니다.
별도 RDB를 신청하려면 동일한 환경의 인스턴스가 먼저 발급되어 있어야 합니다.
발급 전 확인
저장할 정보와 사용할 환경을 코딩 에이전트와 함께 정리합니다.
| 준비 항목 | 안내 |
|---|---|
| 선행 인스턴스 | RDB와 동일한 Staging 또는 Production 환경의 인스턴스가 활성 상태인지 확인합니다. |
| 환경 | 기능 검증용 정보는 Staging, 실제 사용자 정보는 Production에 저장합니다. |
| 저장할 정보 | 회원, 게시글, 예약 등 보관할 항목과 필요한 검색·수정 기능을 정리합니다. |
| 내장 PostgreSQL | 인스턴스에 PostgreSQL을 함께 설치했다면 별도 RDB가 필요한지 먼저 확인합니다. |
발급 및 활성화
전자 결재 승인 후 발급 활성화와 연결 설정을 진행합니다.
프로젝트 상세의 RDB에서 필요한 환경의 발급을 선택합니다.
프로젝트와 환경이 정확한지 확인하고 신청을 제출합니다.
전자 결재 승인 후 프로젝트 상세에서 발급을 활성화합니다.
발급 정보를 프로젝트 환경 변수에 등록합니다.
활성화 후 확인
발급 카드의 연결 정보는 각각 다른 역할을 담당합니다.
| 연결 정보 | 의미 |
|---|---|
| Name | 프로젝트가 사용할 데이터베이스의 이름입니다. |
| Host | 데이터베이스가 위치한 주소입니다. |
| Port | 데이터베이스에 연결할 때 사용하는 통로 번호입니다. |
| User | 데이터베이스 연결 권한을 확인하는 사용자 이름입니다. |
| Password | 연결 권한을 확인하는 비밀값입니다. |
연결 정보는 코드가 아닌 환경 변수로 관리합니다.
Password는 Git 저장소, 메신저 또는 화면 캡처에 포함하지 마십시오.
그룹웨어 SSO 연동
SSO란
프로젝트마다 새로운 비밀번호를 만들지 않고 그룹웨어를 통해 사용자의 신원을 확인합니다. 프로젝트는 전달받은 사용자 정보를 바탕으로 로그인 상태를 만들고, 필요한 경우 사용자별 접근 권한을 구분합니다.
로그인 처리 흐름
사용자는 프로젝트와 그룹웨어 사이를 이동하며 한 번의 인증을 완료합니다.
사용자가 프로젝트에서 로그인 버튼을 선택합니다.
그룹웨어 로그인 화면에서 사내 계정으로 인증합니다.
인증 결과와 함께 등록된 Redirect URI로 돌아옵니다.
프로젝트가 사용자를 확인하고 로그인 상태를 생성합니다.
선택 기준
프로젝트의 이용 대상과 계정 체계에 따라 SSO 연동 여부를 결정합니다.
| 프로젝트의 상황 | 권장 방식 |
|---|---|
| PlusX 구성원만 이용하고 사내 계정으로 사용자를 확인해야 하는 경우 | 그룹웨어 SSO를 연동합니다. |
| 로그인 없이 누구나 이용하는 경우 | SSO를 신청하지 않아도 됩니다. |
| 외부 고객의 가입이나 별도 멤버십을 운영하는 경우 | 프로젝트에 별도의 회원가입과 인증 기능을 구현해야 합니다. |
SSO는 사용자의 신원을 확인하는 기능입니다.
사용자별 메뉴나 데이터 접근 범위는 프로젝트 내부에서 별도로 설정해야 합니다.
연동 전 확인
환경과 로그인 후 이동할 주소를 사전에 확인합니다.
| 준비 항목 | 안내 |
|---|---|
| Dev | 내 컴퓨터에서 연결을 검증할 때 사용합니다. 인스턴스 없이 서비스 도메인을 직접 입력할 수 있습니다. |
| Staging·Production | 동일한 환경의 인스턴스가 먼저 필요하며, 발급된 도메인이 서비스 도메인으로 연결됩니다. |
| 서비스 도메인 | 로그인을 시작하는 프로젝트의 기본 주소입니다. 발급 후 변경할 수 없으므로 정확하게 확인합니다. |
| Redirect URI | 로그인 완료 후 사용자를 다시 이동시킬 프로젝트 내부의 정확한 주소입니다. |
| Post-Logout URI | 로그아웃 완료 후 사용자를 이동시킬 주소입니다. |
신청 및 연결
승인 후 발급된 값을 프로젝트 설정에 연결하고 로그인과 로그아웃을 검증합니다.
프로젝트 상세의 SSO에서 환경과 서비스 도메인을 확인합니다.
연결할 프로젝트와 환경이 정확한지 확인하고 제출합니다.
승인 후 Client ID, Client Secret 및 URI를 환경 변수에 등록합니다.
시크릿 모드에서 로그인과 로그아웃을 각각 확인합니다.
승인 후 확인
발급 카드에 표시된 값의 역할을 확인한 후 프로젝트에 연결합니다.
| 발급 정보 | 의미 |
|---|---|
| Client ID | 어떤 프로젝트의 로그인 요청인지 구분하는 공개 식별값입니다. |
| Client Secret | 프로젝트가 그룹웨어에 자신을 증명할 때 사용하는 비밀값입니다. |
| Redirect URI | 로그인 성공 후 사용자가 돌아오는 주소입니다. |
| Post-Logout URI | 로그아웃 후 사용자가 이동하는 주소입니다. |
Client Secret은 비밀번호와 같은 민감 정보입니다.
코드나 Git 저장소에 포함하지 않고 환경 변수로 관리하십시오.
스테이션 공개
스테이션이란
프로젝트 이름, 설명, 이미지, 이용 방법 및 접근 권한을 등록하여 사내 구성원에게 공개합니다. 인스턴스로 공개한 웹 프로젝트뿐 아니라 별도 자원이 필요하지 않은 설치형 프로그램도 릴리즈할 수 있습니다.
공개 방식 확인
프로젝트 형태에 따라 스테이션 릴리즈 전에 준비할 항목이 달라집니다.
| 프로젝트 형태 | 릴리즈 전 준비 |
|---|---|
| 인스턴스로 실행하는 웹 프로젝트 | 인스턴스가 활성 상태이고 접속 도메인에서 주요 기능이 동작하는지 확인합니다. |
| 설치형 프로그램 | 설치 파일과 지원 운영체제를 확인합니다. 인스턴스 및 RDB 발급은 필수가 아닙니다. |
스테이션은 프로젝트를 직접 실행하는 공간이 아닙니다.
웹 프로젝트는 등록할 링크가 정상적으로 열리는지, 설치형 프로그램은 첨부 파일이 정상적으로 설치되는지 먼저 확인합니다.
릴리즈 정보 준비
처음 접하는 구성원도 프로젝트의 목적과 이용 방법을 이해할 수 있도록 작성합니다.
| 준비 항목 | 안내 |
|---|---|
| 기본 분류 | 카테고리, 접근 권한, 배포 형태, 지원 기기 및 운영체제를 선택합니다. |
| 이용 경로 | 웹 프로젝트의 접근 링크 또는 설치형 프로그램의 첨부 파일을 준비합니다. |
| 소개 문구 | 프로젝트의 목적이 드러나는 한 줄 소개와 주요 기능을 설명하는 상세 내용을 작성합니다. |
| 이미지 | 프로젝트 아이콘, PWA 아이콘, 썸네일, 메인 이미지 및 스크린샷을 준비합니다. |
| 버전 정보 | 최초 버전과 주요 변경 내용을 구성원이 이해할 수 있는 문장으로 작성합니다. |
릴리즈 절차
스테이션 릴리즈는 1차와 2차 전자 결재가 모두 완료된 후 공개됩니다.
프로젝트 상세의 스테이션에서 기본 정보와 이용 경로를 입력합니다.
아이콘, 대표 이미지 및 스크린샷을 등록합니다.
입력 내용을 확인하고 스테이션 릴리즈를 제출합니다.
1차와 2차 승인이 완료되면 스테이션에 공개됩니다.
공개 후 관리
변경하려는 항목에 따라 신청 유형을 구분합니다.
| 변경 상황 | 진행 방법 |
|---|---|
| 한 줄 소개, 상세 설명 또는 기본 정보 변경 | 정보 수정 신청을 제출합니다. |
| 아이콘, 대표 이미지 또는 스크린샷 변경 | 이미지 수정 신청을 제출합니다. |
| 새로운 기능이나 버전 공개 | 버전과 변경 내용을 추가하여 최신 정보를 유지합니다. |
| 공개 상태 확인 | 스테이션에서 프로젝트 상세 정보, 최신 버전 및 이용 경로를 확인합니다. |
접근 권한에 포함된 구성원만 프로젝트를 확인할 수 있습니다.
공개 후 프로젝트가 보이지 않는다면 최종 승인 상태와 접근 권한을 먼저 확인합니다.
전자결재
전자결재란
인스턴스 발급, RDB 연결 및 Station 릴리즈처럼 비용, 보안 또는 다른 사용자에게 영향을 주는 작업은 승인 후 진행됩니다. 프로젝트 생성처럼 영향이 제한적인 작업은 결재 없이 즉시 처리됩니다.
결재 대상
작업의 영향 범위에 따라 전자결재 필요 여부가 달라집니다.
| 작업 | 처리 방식 |
|---|---|
| 인스턴스, RDB 또는 SSO 발급·변경·삭제 | 전자결재를 제출하고 승인 상태를 확인합니다. |
| Station 릴리즈 또는 공개 정보 변경 | 1차와 2차 검토가 필요한 신청은 최종 승인 후 반영됩니다. |
| 프로젝트 생성 | 별도 결재 없이 즉시 생성됩니다. |
| 인스턴스 시작 등 즉시 실행 가능한 작업 | 화면에 결재 안내가 표시되지 않으면 바로 처리됩니다. |
상태 확인
현재 상태에 따라 기다리거나 후속 작업을 진행합니다.
| 상태 | 의미와 다음 작업 |
|---|---|
| 대기 | 담당자가 신청 내용을 검토 중입니다. 동일한 신청을 반복하지 않고 현재 결재 단계를 확인합니다. |
| 1차 승인 | 2단계 결재 대상은 최종 승인 전까지 변경 사항이 반영되지 않습니다. |
| 최종 승인 | 신청이 허용된 상태입니다. 자원 종류에 따라 활성화 또는 연결 작업을 진행합니다. |
| 반려 | 상세 사유를 확인하고 요청된 내용을 보완하여 다시 신청합니다. |
신청 및 처리
신청 대상과 환경을 확인한 후 진행 상태에 맞게 처리합니다.
프로젝트, 환경, 신청 유형 및 변경 대상을 확인합니다.
작업 목적과 필요한 이유를 구체적으로 작성하여 제출합니다.
전자결재에서 현재 승인 단계와 반려 사유를 확인합니다.
최종 승인 후 자원을 활성화하거나 발급값을 연결합니다.
승인 후 진행
승인만으로 모든 작업이 완료되는 것은 아니므로 신청 유형별 후속 단계를 확인합니다.
| 신청 유형 | 승인 후 작업 |
|---|---|
| 인스턴스 | 프로젝트 상세에서 발급을 활성화하고 PEM 키와 접속 정보를 보관합니다. |
| RDB | 발급을 활성화한 후 연결 정보를 환경 변수에 등록합니다. |
| SSO | Client ID, Client Secret 및 URI를 연결하고 로그인·로그아웃을 검증합니다. |
| Station | 최종 승인 후 공개 상태와 접근 권한을 확인합니다. |
자원 정리
연결 관계가 있는 항목부터 순서대로 정리하면 삭제 제한과 서비스 중단을 줄일 수 있습니다.
공개 정보와 이용 중인 접근 경로의 영향을 먼저 확인합니다.
인스턴스 환경에 연결된 로그인과 데이터 저장 자원을 확인합니다.
프로젝트를 실행하던 공간을 정리합니다.
진행 중인 신청과 남은 자원이 없는지 확인한 후 삭제합니다.
삭제한 항목은 복구할 수 없습니다.
화면에 표시된 대상 환경과 함께 삭제되는 항목을 확인한 후 진행하십시오.
문제 해결
문제 확인 방법
프로젝트명, 환경, 현재 상태, 오류 문구 및 문제가 시작된 시점을 기록하면 원인을 빠르게 찾을 수 있습니다. 새로고침이나 같은 작업의 반복만으로 해결되지 않는 경우 아래 항목을 순서대로 확인합니다.
민감 정보는 화면 캡처나 대화에 포함하지 마십시오.
Client Secret, Password 및 PEM 키의 내용은 관리자나 코딩 에이전트에게도 그대로 전달하지 않습니다.
프로젝트 실행과 배포
| 증상 | 확인 방법 |
|---|---|
| 다른 사용자가 웹 프로젝트에 접속할 수 없음 | 프로젝트가 내 컴퓨터에서만 실행 중인지 확인합니다. 웹 프로젝트는 인스턴스로 배포해야 합니다. |
| 도메인은 열리지만 주요 기능이 작동하지 않음 | 인스턴스가 활성 상태인지, 최신 코드와 환경 변수가 연결되었는지 확인합니다. |
| 설치형 프로그램의 실행 파일을 찾을 수 없음 | Station에 등록된 첨부 파일과 지원 운영체제를 확인합니다. 설치형 프로그램은 인스턴스가 없어도 릴리즈할 수 있습니다. |
자원 발급과 연결
| 증상 | 확인 방법 |
|---|---|
| 발급 버튼이 비활성 상태임 | 동일한 신청이 진행 중이거나 선행 자원이 없을 수 있습니다. 버튼에 마우스를 올려 표시되는 사유를 확인합니다. |
| 승인 후 자원이 표시되지 않음 | 인스턴스와 RDB는 프로젝트 상세에서 발급 활성화가 필요할 수 있습니다. 활성화를 시작한 후 상태를 다시 확인합니다. |
| RDB에 연결할 수 없음 | RDB와 인스턴스의 환경이 같은지 확인하고 Host, Port, Name 및 User가 정확한지 점검합니다. Password 앞뒤의 공백도 확인합니다. |
| PEM 키를 분실함 | PEM 키는 다시 다운로드할 수 없습니다. 관리자와 영향 범위를 확인한 후 인스턴스 재생성을 검토합니다. |
SSO와 Station
| 증상 | 확인 방법 |
|---|---|
| SSO 로그인 후 프로젝트로 돌아오지 않음 | Redirect URI의 도메인과 경로가 프로젝트 설정과 정확히 일치하는지 확인합니다. 서로 다른 환경의 값을 혼용하지 않았는지도 확인합니다. |
| SSO 로그인 또는 권한 확인에 실패함 | Client ID와 Client Secret이 동일한 환경의 값인지 확인합니다. Client Secret에 공백이나 따옴표가 포함되지 않도록 주의합니다. |
| Station 승인 후 프로젝트가 보이지 않음 | 릴리즈가 최종 승인 상태인지, 접근 권한에 현재 사용자가 포함되어 있는지 확인합니다. |
| Station에서 프로젝트를 실행할 수 없음 | Station은 프로젝트를 직접 실행하지 않습니다. 웹 프로젝트는 등록된 도메인과 자원 상태를, 설치형 프로그램은 첨부 파일과 실행 환경을 확인합니다. |
전자결재와 삭제
| 증상 | 확인 방법 |
|---|---|
| 신청이 반려됨 | 전자결재 상세에서 사유를 확인하고 요청된 내용을 보완하여 다시 신청합니다. 이전 신청을 변경 없이 반복하지 않습니다. |
| 프로젝트를 삭제할 수 없음 | 진행 중인 신청과 Station 공개 정보를 먼저 정리하고, 연결된 SSO·RDB 및 인스턴스가 남아 있는지 확인합니다. |
| 어떤 자원부터 삭제해야 하는지 알 수 없음 | Station → SSO·RDB → 인스턴스 → 프로젝트 순서로 연결 관계와 영향 범위를 확인합니다. |
| 삭제 팝업에 여러 항목이 표시됨 | 함께 정리되는 환경, 도메인 및 연결 자원을 모두 확인합니다. 삭제 후에는 복구할 수 없습니다. |
해결되지 않는 경우
관리자 또는 코딩 에이전트가 동일한 문제를 확인할 수 있도록 아래 정보를 정리합니다.
| 기록할 정보 | 예시 |
|---|---|
| 위치 | 프로젝트명, 메뉴명 및 Staging·Production 등의 환경 |
| 수행한 작업 | 선택한 버튼과 입력한 항목을 발생 순서대로 기록 |
| 표시된 결과 | 현재 상태, 오류 문구 및 문제가 발생한 시각 |
| 재현 여부 | 새로고침 후 같은 작업을 수행했을 때 동일하게 발생하는지 확인 |
용어 정리
프로젝트와 배포
프로젝트를 만들고 다른 사용자가 이용할 수 있도록 준비하는 과정에서 사용하는 기본 용어입니다.
| 용어 | 의미 |
|---|---|
| 프로젝트 | 하나의 배포 대상에 필요한 자원, 접근 정보 및 Station 정보를 함께 관리하는 단위입니다. |
| 배포 | 내 컴퓨터에서 만든 프로젝트를 다른 사용자가 웹으로 접속하거나 설치하여 이용할 수 있는 상태로 전환하는 과정입니다. |
| 프론트엔드 | 버튼, 입력창, 목록 및 화면 이동처럼 사용자가 직접 확인하고 조작하는 영역입니다. |
| 백엔드 | 로그인 확인, 정보 처리와 저장 및 자동 작업처럼 화면 뒤에서 실행되는 기능입니다. |
| API | 화면과 기능 또는 서로 다른 시스템이 정해진 규칙에 따라 정보를 주고받는 연결 방식입니다. |
환경과 주소
프로젝트의 개발 단계와 접속 위치를 구분할 때 사용하는 용어입니다.
| 용어 | 의미 |
|---|---|
| Dev | 기능을 개발하고 빠르게 검증하는 개발 환경입니다. |
| Staging | 실제 공개 전에 구성원과 기능 및 설정을 확인하는 테스트 환경입니다. |
| Production | 실제 사용자가 접속하여 프로젝트를 이용하는 운영 환경입니다. |
| 도메인 | 사용자가 웹 프로젝트에 접속할 때 입력하거나 선택하는 주소입니다. |
| 슬러그(Slug) | 도메인에 포함되어 프로젝트를 구분하는 짧은 영문 식별자입니다. 예: my-project |
| 환경 변수 | Password, 도메인 및 연결 정보처럼 환경마다 다르거나 코드에 직접 작성하면 안 되는 설정값입니다. |
발급 자원
프로젝트의 실행, 공개 및 정보 저장에 필요한 자원입니다.
| 용어 | 의미 |
|---|---|
| 인스턴스 | 내 컴퓨터가 꺼져 있어도 프로젝트를 계속 실행하는 원격 컴퓨터입니다. 서버 기능이 있는 웹 프로젝트에 사용합니다. |
| RDB | 회원, 게시글 및 예약처럼 일정한 항목으로 나뉘는 정보를 표 구조로 저장하고 조회하는 관계형 데이터베이스입니다. |
| PostgreSQL | Developers에서 RDB를 제공할 때 사용하는 데이터베이스 관리 시스템입니다. |
| IP 주소 | 네트워크에서 인스턴스나 RDB의 위치를 구분하는 숫자 형식의 주소입니다. |
| PEM 키 | 인스턴스에 안전하게 접속할 때 사용하는 1회 발급 파일입니다. 다시 다운로드할 수 없으므로 승인된 보안 저장소에 보관합니다. |
인스턴스 및 RDB는 모든 프로젝트에 필요한 자원이 아닙니다.
프로젝트의 실행 방식과 기능을 확인한 후 필요한 자원만 발급합니다.
로그인과 인증
그룹웨어 계정으로 안전하게 로그인하기 위해 사용하는 용어입니다.
| 용어 | 의미 |
|---|---|
| SSO | 별도의 회원가입 없이 그룹웨어 계정으로 프로젝트에 로그인하는 기능입니다. |
| Client ID | SSO가 어떤 프로젝트의 로그인 요청인지 구분할 때 사용하는 공개 식별값입니다. |
| Client Secret | 프로젝트가 SSO에 자신을 증명할 때 사용하는 비밀값입니다. Password와 같이 외부에 공개해서는 안 됩니다. |
| Redirect URI | SSO 로그인을 마친 사용자를 다시 프로젝트로 돌려보낼 정확한 주소입니다. |
| Post-Logout URI | SSO 로그아웃을 마친 사용자를 이동시킬 정확한 주소입니다. |
Station과 전자결재
완성된 프로젝트를 사내에 공개하고 변경 사항을 승인받을 때 사용하는 용어입니다.
| 용어 | 의미 |
|---|---|
| Station | 완성된 사내 프로젝트를 소개하고 접근 권한이 있는 구성원이 찾아 이용할 수 있도록 연결하는 서비스 허브입니다. |
| 릴리즈 | 프로젝트의 소개 정보, 이용 경로 또는 설치 파일을 Station에 제출하여 공개하는 절차입니다. |
| 버전 | 프로젝트의 변경 상태를 구분하기 위한 번호입니다. 새로운 기능이나 중요한 변경 사항을 공개할 때 함께 기록합니다. |
| 접근 권한 | Station에서 프로젝트를 확인하거나 이용할 수 있는 사용자 또는 조직의 범위입니다. |
| 전자결재 | 공용 자원과 사내 공개 정보의 신청 내용을 담당자가 검토하고 승인하는 절차입니다. |
| 2단계 결재 | 1차 담당자가 신청 내용을 검토한 후 최고 관리자가 최종 승인하는 절차입니다. |