클로드나 gpt로 사이트 첫 설계도 작성시..

# 📘 효율적인 시스템 설계서 작성법 - 실전 예시 기반

개발을 하다 보면 "정말 잘 짜여진 설계서"가 얼마나 중요한지 뼈저리게 느끼게 됩니다. 특히 **팀 단위 개발**, 또는 **B2B 서비스 운영**에서는 더더욱 그렇죠. 오늘은 제가 실제로 활용하는 설계 방식 중 일부를 응용하여, **"프레임워크 없이도 완전히 작동하는 시스템 설계서"** 작성법을 예시와 함께 소개해드릴게요.

---

## ✅ 핵심 원칙 5가지

1. **DB 테이블 스키마는 하나의 문서에서 모두 정의**

2. **모든 함수는 네이밍 규칙을 따름**

3. **ENUM 비교 시 문자열로만 처리 (`=== 'active'` 등)**

4. **리턴 포맷은 반드시 `['success' => true/false, ...]`**

5. **에러 발생 시 항상 이유가 포함된 메시지 반환**

---

## 📦 예시 설계 구조

> 아래는 예시 시스템 `MyBid`의 일부 설계입니다. 실제와 유사하나 구조만 참고용으로 제공합니다.

### 🔹 테이블 예시

```sql

CREATE TABLE my_user (

    id INT AUTO_INCREMENT PRIMARY KEY,

    login_id VARCHAR(50) UNIQUE NOT NULL,

    password VARCHAR(255) NOT NULL,

    email VARCHAR(100) UNIQUE NOT NULL,

    role ENUM('user', 'manager', 'admin') DEFAULT 'user',

    status ENUM('active', 'suspended') DEFAULT 'active',

    created_at DATETIME DEFAULT CURRENT_TIMESTAMP

);

```

### 🔹 함수 네이밍 규칙

- `my_user_create($data)` : 사용자 생성

- `my_user_get($id)` : 사용자 단건 조회

- `my_user_list($filter)` : 사용자 목록

- `my_user_update($id, $data)` : 수정

- `my_user_delete($id)` : 삭제

### 🔹 유틸 함수 예시

```php

function util_hash_password($plain) {

    return password_hash($plain, PASSWORD_BCRYPT);

}

function util_verify_password($plain, $hash) {

    return password_verify($plain, $hash);

}

```

---

## 🧩 실제 구현 함수 예시

```php

function my_user_get($id) {

    global $db;

    if (!is_numeric($id)) {

        return ['success' => false, 'error' => 'Invalid ID'];

    }

    $stmt = mysqli_prepare($db, "SELECT * FROM my_user WHERE id = ?");

    mysqli_stmt_bind_param($stmt, "i", $id);

    mysqli_stmt_execute($stmt);

    $result = mysqli_stmt_get_result($stmt);

    if ($row = mysqli_fetch_assoc($result)) {

        unset($row['password']); // 비밀번호 제거

        return ['success' => true, 'data' => $row];

    }

    return ['success' => false, 'error' => 'User not found'];

}

```

---

## 🗂 페이지 매핑 예시

| 페이지명 | 주요 기능 | 사용 함수 |

|----------------------|----------------------------------|-------------------------------------|

| `login.php` | 로그인 처리 | `my_user_get()`, `util_verify_password()` |

| `register.php` | 회원가입 | `my_user_create()`, `util_hash_password()` |

| `admin_users.php` | 관리자용 회원관리 | `my_user_list()`, `my_user_update()` |

| `profile.php` | 내 정보 조회/수정 | `my_user_get()`, `my_user_update()` |

---

## 📎 실전 팁

- 프레임워크를 쓰지 않아도, **규칙만 지키면 개발 속도가 훨씬 빨라집니다**.

- 함수 이름만 봐도 기능이 명확히 드러나야 합니다.

- 유틸리티 함수는 꼭 따로 모아서 관리하세요.

- 페이지마다 어떤 함수가 쓰이는지 매핑표를 만들면 협업이 쉬워집니다.

---

## ✅ 마무리

설계서가 명확하면, 개발 속도도 배가 됩니다.  

"한 명이 만든 구조"가 아니라, **"모두가 이해할 수 있는 체계"**로 작성해야 오랜 시간 안정적으로 운영할 수 있습니다.

저는 이런 방식으로 중소규모 웹서비스부터 꽤 정교한 분석 시스템까지 구축한 경험이 있는데요, 다음 포스팅에서는 **입찰 시뮬레이터처럼 특수 로직이 많은 시스템의 설계 방식**도 소개해드릴게요.

읽어주셔서 감사합니다.

문구는 잘 다듬어주긴 하네요.

[요약]

1. php로 정의할 함수 접두접미규칙 및 스키마랑 동일하게.

2. 커서같은 에이전트에게 항상 참조시켜서 자기 마음대로 못 만들게 강제 규칙을 적용.

3. 미리 정한만큼 디버깅시에도 용이.