AGENTS.md, PROJECT_RULES.md, CODING_GUIDE.md 샘플까지 한 번에 정리

AI 코딩 도구를 사용할 때 가장 많이 하는 실수가 있습니다.

“알아서 만들어줘.”

처음에는 그럴듯한 결과가 나옵니다. 하지만 프로젝트가 커질수록 문제가 생깁니다. 화면 스타일이 달라지고, DB 구조를 마음대로 바꾸고, 로그 처리 방식이 제각각이 되고, 기존 규칙과 맞지 않는 코드가 만들어집니다.

그래서 필요한 것이 바로 가이드 문서입니다.

Codex 같은 AI 코딩 에이전트는 단순히 명령을 받아 코드를 만드는 도구가 아닙니다. 프로젝트의 구조, 개발 규칙, 금지 사항, 테스트 방법, 완료 기준을 알려주면 훨씬 안정적으로 작업합니다.

특히 OpenAI Codex는 AGENTS.md 파일을 작업 전에 읽고, 프로젝트별 지침으로 활용할 수 있습니다. OpenAI 공식 문서에서도 AGENTS.md는 Codex가 작업 전에 읽는 프로젝트 지침 파일이며, 저장소 구조, 실행 방법, 빌드·테스트 명령, 개발 규칙, 금지 사항, 완료 기준 등을 담는 것이 좋다고 설명합니다.

1. AGENTS.md란?

AGENTS.md는 쉽게 말하면 AI 개발자를 위한 작업 지시서입니다.

사람 개발자에게 프로젝트를 맡길 때도 이런 설명이 필요합니다.

이 프로젝트는 어떤 구조인지
어떤 언어와 프레임워크를 쓰는지
DB는 무엇을 쓰는지
빌드는 어떻게 하는지
화면 디자인 기준은 무엇인지
절대 변경하면 안 되는 파일은 무엇인지
수정 후 어떤 테스트를 해야 하는지

이 내용을 Codex에게 알려주는 대표 파일이 AGENTS.md입니다.

OpenAI는 AGENTS.md를 “에이전트를 위한 README”처럼 생각할 수 있다고 설명합니다. 또한 한 번 잘 만든 지침을 매번 프롬프트에 반복해서 쓰지 않고, 저장소 안에 넣어 재사용하는 방식이 좋다고 안내합니다.

2. 왜 AGENTS.md가 중요한가?

Codex를 그냥 사용하면 매번 다른 방식으로 결과를 만들 수 있습니다.

예를 들어 WinForms 프로젝트에서 어떤 날은 버튼 이름을 btnSave로 만들고, 어떤 날은 saveButton으로 만들 수 있습니다. 어떤 날은 DB 연결 문자열을 코드에 직접 넣고, 어떤 날은 설정 파일을 만들 수 있습니다. 어떤 날은 예외 처리를 MessageBox.Show()로 끝내고, 어떤 날은 로그 파일을 만들 수도 있습니다.

사람이 보기에는 모두 코드지만, 실제 운영 시스템에서는 이런 차이가 큰 문제가 됩니다.

특히 MES, ERP, FEMS 같은 업무 시스템에서는 개발 규칙이 중요합니다.

DB 구조를 함부로 바꾸면 안 됩니다.
기준정보 테이블 사용 방식이 통일되어야 합니다.
로그 저장 위치가 일정해야 합니다.
화면 버튼 위치와 명칭이 일관되어야 합니다.
오류가 발생해도 프로그램이 종료되지 않아야 합니다.
운영 DB와 테스트 DB를 구분해야 합니다.

AGENTS.md는 이런 규칙을 Codex가 계속 기억하고 따르도록 만드는 기준 문서입니다.

3. AGENTS.md와 다른 가이드 문서의 차이

프로젝트에 가이드 문서를 만들 때 AGENTS.md 하나만 있어도 시작은 가능합니다. 하지만 프로젝트가 커지면 문서를 나누는 것이 좋습니다.

추천 구조는 다음과 같습니다.

프로젝트 루트
├─ AGENTS.md
├─ PROJECT_RULES.md
├─ CODING_GUIDE.md
├─ DESIGN_GUIDE.md
├─ DB_SCHEMA.md
├─ API_SPEC.md
├─ BUILD_GUIDE.md
├─ TEST_GUIDE.md
└─ RELEASE_GUIDE.md

각 문서의 역할은 다릅니다.

AGENTS.md는 Codex가 항상 먼저 읽어야 하는 핵심 지침입니다.

PROJECT_RULES.md는 프로젝트 전체 원칙입니다.

CODING_GUIDE.md는 코딩 스타일, 네이밍, 예외 처리, 로그 규칙입니다.

DESIGN_GUIDE.md는 화면 디자인, 버튼 위치, 색상, 입력 필드 기준입니다.

DB_SCHEMA.md는 DB 구조와 테이블 사용 원칙입니다.

API_SPEC.md는 API 주소, 요청·응답 구조, 오류 처리 기준입니다.

BUILD_GUIDE.md는 빌드, 실행, 배포 방법입니다.

TEST_GUIDE.md는 테스트 시나리오와 확인 방법입니다.

RELEASE_GUIDE.md는 버전 관리, 출시노트, 배포 전 점검 기준입니다.

OpenAI 문서에서도 AGENTS.md가 너무 커지면 핵심만 담고, 작업별 세부 문서는 별도 Markdown 파일로 분리해 참조하는 방식이 좋다고 안내합니다.

4. AGENTS.md 작성 원칙

AGENTS.md는 길다고 좋은 문서가 아닙니다.

짧지만 정확해야 합니다.

좋은 AGENTS.md에는 다음 내용이 들어가면 좋습니다.

프로젝트 목적
사용 기술
폴더 구조
중요 파일
실행 방법
빌드 방법
테스트 방법
코딩 규칙
DB 변경 규칙
금지 사항
작업 완료 기준
수정 후 보고 방식

반대로 다음 내용은 피하는 것이 좋습니다.

너무 추상적인 표현
“깔끔하게”, “예쁘게”, “알아서” 같은 애매한 지시
실제 프로젝트와 맞지 않는 오래된 규칙
지나치게 긴 설명
중복된 내용
이미 폐기된 기능 설명

핵심은 Codex가 실수하지 않도록 반복적으로 지켜야 할 규칙을 담는 것입니다.

5. AGENTS.md 샘플

아래는 MES Lite, C# WinForms, MariaDB 프로젝트를 기준으로 한 샘플입니다.

# AGENTS.md

## 1. Project Overview

This project is MES Lite, a lightweight manufacturing execution system for small and mid-sized manufacturers.

The main goals are:

- Manage master data such as items, customers, equipment, process, BOM, and work centers.
- Manage work orders, production progress, material input, production results, and defects.
- Keep the system simple, flexible, and easy to maintain.
- Support future AI-assisted maintenance by internal IT operators.

## 2. Tech Stack

- Language: C#
- UI: Windows Forms
- Database: MariaDB
- Target OS: Windows
- Future extension: C# MAUI for mobile and tablet
- Legacy reference: Existing VB6 source may be used only as a functional reference.

## 3. Important Documents

Before modifying code, read the following files when relevant:

- PROJECT_RULES.md
- CODING_GUIDE.md
- DESIGN_GUIDE.md
- DB_SCHEMA.md
- API_SPEC.md
- BUILD_GUIDE.md
- TEST_GUIDE.md

If a required rule is missing, explain the assumption before implementing.

## 4. Repository Rules

- Do not change the database schema unless explicitly requested.
- Do not hardcode DB passwords, API keys, or server credentials.
- Do not remove existing business logic without explaining why.
- Do not rename public methods, forms, or controls unless necessary.
- Keep changes small and focused.
- Modify only files related to the requested task.

## 5. Coding Rules

- Use clear C# naming conventions.
- Use try-catch for DB, network, file, and API operations.
- Log errors instead of allowing the application to crash.
- Keep UI code and business logic separated where possible.
- Avoid duplicate code.
- Prefer existing utility classes before creating new ones.

## 6. UI Rules

- Keep the existing Newman-style modern design.
- Align labels and input fields consistently.
- Buttons must be easy to understand for manufacturing users.
- Do not add unnecessary buttons.
- Remove unused controls only after confirming they are not referenced.

## 7. Database Rules

- Use existing flexible table structures first.
- Prefer codeM/codeD for common codes.
- Prefer objectM/objectD for object-style master data such as equipment, BOM, and routing.
- Prefer PlanM/PlanD for plans such as work orders, purchase orders, and sales orders.
- Prefer ProcessM/ProcessD for business transactions other than stock.
- Prefer stockM/stockD for inventory and stock history.
- Any schema change must be proposed first and implemented only after approval.

## 8. Build and Test

After modifying code:

- Check for compile errors.
- Check null reference risks.
- Check DB exception handling.
- Check whether the modified screen opens normally.
- Summarize changed files.
- Explain how to test the change manually.

## 9. Output Format

When finishing a task, report:

1. Summary of changes
2. Modified files
3. Important implementation notes
4. Test checklist
5. Remaining risks or assumptions

이 정도만 있어도 Codex의 작업 품질이 상당히 좋아집니다.

6. PROJECT_RULES.md 샘플

PROJECT_RULES.md는 프로젝트의 전체 원칙을 정리하는 문서입니다.

# PROJECT_RULES.md

## 1. Project Direction

MES Lite must remain simple, flexible, and practical.

The system is designed for small and mid-sized manufacturers that need core MES functions without heavy customization.

The project must prioritize:

- Simple operation
- Flexible data structure
- Fast implementation
- Easy maintenance
- Internal IT operator training
- AI-assisted future development

## 2. Functional Scope

Core scope:

- Item management
- Customer and vendor management
- Equipment management
- Process management
- BOM management
- Routing management
- Work order management
- Production progress tracking
- Material input
- Production result
- Defect result
- Inventory transaction
- Stock history
- Basic reports

Out of scope unless explicitly requested:

- Complex ERP accounting
- Payroll
- Advanced APS scheduling
- Full WMS
- Full SCM
- AI prediction model

## 3. Development Policy

- Keep screens simple.
- Avoid excessive popups.
- Avoid unnecessary configuration.
- Do not create new tables when existing flexible tables can handle the requirement.
- Prefer practical business usability over technical complexity.
- Make all important errors visible through logs.

## 4. Database Policy

Database flexibility is a core design principle.

The system should allow new business objects and attributes through code and object tables where possible, instead of frequent schema changes.

Schema changes are allowed only when:

- Existing flexible tables are not suitable.
- Performance or data integrity requires a separate table.
- The change is documented in DB_SCHEMA.md.
- Migration SQL is provided separately.

## 5. User Experience Policy

The primary users are manufacturing workers, production managers, and internal IT operators.

Therefore:

- Use familiar terminology.
- Avoid developer-oriented words on screens.
- Make input order match actual work order.
- Keep required fields clear.
- Show meaningful error messages.
- Do not expose raw exception messages to general users.

## 6. Maintenance Policy

Every new feature should be maintainable by an internal IT operator with basic training.

For each major function, provide:

- Screen purpose
- Main data flow
- Related tables
- Manual test method
- Common error cases

7. CODING_GUIDE.md 샘플

CODING_GUIDE.md는 실제 개발 스타일을 정합니다.

# CODING_GUIDE.md

## 1. C# Naming Rules

Use the following naming conventions:

- Class: PascalCase
- Method: PascalCase
- Property: PascalCase
- Local variable: camelCase
- Private field: _camelCase
- Button control: btnSave, btnSearch, btnDelete
- TextBox control: txtItemCode, txtItemName
- ComboBox control: cboProcess
- Grid control: grdItems
- Label control: lblItemCode

## 2. Form Rules

Each form should follow this structure:

1. Constructor
2. Initialize event handlers
3. Load data
4. Search methods
5. Save methods
6. Delete methods
7. Validation methods
8. Utility methods

## 3. Exception Handling

All DB, file, network, and API logic must use try-catch.

Bad example:

```csharp
var result = db.Execute(query);

Good example:

try
{
    var result = db.Execute(query);
}
catch (Exception ex)
{
    Logger.Error(ex, "Failed to execute item search.");
    MessageBox.Show("조회 중 오류가 발생했습니다. 관리자에게 문의하세요.");
}

4. Logging Rules

Logs must be saved under the log folder below the executable path.
Log file name format: yyyyMMdd.txt
Log must include time, level, screen name, function name, and error message.
Do not stop the application because of logging failure.

Example:

2026-07-02 10:30:12 [ERROR] frmItem.SearchItems - DB connection failed.

5. SQL Rules

Do not concatenate user input directly into SQL.
Use parameters.
Keep SQL readable.
Avoid SELECT * in production code.
Add comments for complex SQL.

Bad example:

string sql = "SELECT * FROM itemM WHERE itemName = '" + txtItemName.Text + "'";

Good example:

string sql = "SELECT itemCode, itemName, spec FROM itemM WHERE itemName = @itemName";

6. Validation Rules

Before saving data, validate:

Required fields
Duplicate keys
Date format
Numeric values
Code existence
Business rule conflicts

7. Code Review Checklist

Before completing a task, check:

Does it compile?
Are exceptions handled?
Is logging applied?
Are DB parameters used?
Is the UI consistent?
Are unused controls removed?
Is the change limited to the requested scope?


---

# 8. DESIGN_GUIDE.md 샘플

화면이 계속 달라지는 문제를 막으려면 디자인 문서가 필요합니다.

```markdown
# DESIGN_GUIDE.md

## 1. Design Direction

The application uses a clean, modern, Newman-style Windows Forms design.

The UI must be simple, practical, and easy for manufacturing users.

## 2. Layout Rules

- Keep labels and input fields aligned.
- Use consistent spacing between rows.
- Use the same height for similar input controls.
- Long input fields should define the base width.
- Align shorter fields to match the same left and top positions.
- Do not place too many controls in one row.
- Keep important buttons visible without scrolling.

## 3. Button Rules

Common button names:

- 조회
- 신규
- 저장
- 수정
- 삭제
- 엑셀업로드
- 엑셀다운로드
- 닫기

Button placement:

- Search buttons: top-right of search area
- Save/Delete buttons: right side or bottom action area
- Close button: far right
- Do not duplicate buttons with the same function.

## 4. Grid Rules

- Main list grid should occupy the largest area.
- Use clear column headers.
- Hide technical columns unless needed.
- Use date and number formats consistently.
- Selection must be obvious.

## 5. Popup Rules

- Use popups only when necessary.
- Confirmation popup is required for delete.
- Error popup must be simple and user-friendly.
- Technical error details should go to logs.

## 6. Screen Naming Rules

Use business-friendly Korean screen names.

Examples:

- 품목관리
- 설비관리
- BOM관리
- 작업지시관리
- 생산실적관리
- 재고현황
- 수불이력

Avoid developer-oriented names on screen titles.

9. DB_SCHEMA.md 샘플

MES Lite처럼 DB 유연성이 중요한 프로젝트는 DB 문서가 매우 중요합니다.

# DB_SCHEMA.md

## 1. Database Design Principle

The MES Lite database must support flexible business changes without frequent schema changes.

Use common master/detail table structures where possible.

## 2. Core Table Groups

### codeM / codeD

Used for common codes.

Examples:

- Item category
- Process type
- Equipment type
- Unit code
- Defect type
- Work status

### objectM / objectD

Used for object-style master data.

Examples:

- Equipment
- BOM
- Routing
- Process definition
- Work center

`objectM.class` references `codeM.seq`.
`objectD.class` references `codeD.seq`.

### PlanM / PlanD

Used for plan-related data.

Examples:

- Work order
- Purchase order
- Sales order
- Production plan

### ProcessM / ProcessD

Used for business process transactions other than stock.

Examples:

- Work start
- Work end
- Production result
- Defect result
- Inspection result

### stockM / stockD

Used for inventory and stock history.

Examples:

- Inbound
- Outbound
- Transfer
- Adjustment
- Material input
- Current stock
- Lot history

## 3. Schema Change Rule

Do not add tables or columns unless required.

Before changing schema, prepare:

1. Reason for change
2. Existing table limitation
3. Proposed table or column
4. Migration SQL
5. Impacted screens
6. Test scenario

## 4. Data Rule

- Use seq as internal key where applicable.
- Use business codes for user-facing identifiers.
- Keep created and updated timestamps.
- Keep user information for important transactions.
- Do not physically delete important transaction data unless explicitly required.

10. API_SPEC.md 샘플

API가 있는 프로젝트라면 이 문서가 필요합니다.

# API_SPEC.md

## 1. API Policy

All API calls must handle:

- Network failure
- Timeout
- Invalid response
- Empty response
- Authentication failure
- Server error

The application must not crash because of API failure.

## 2. Common Request Rule

- Use JSON unless otherwise specified.
- Use UTF-8.
- Set timeout.
- Log request result.
- Do not log sensitive information.

## 3. Common Response Format

Recommended response format:

```json
{
  "success": true,
  "message": "OK",
  "data": {}
}

Error response:

{
  "success": false,
  "message": "Invalid request",
  "errorCode": "INVALID_REQUEST"
}

4. Error Handling

User message:

서버 통신 중 오류가 발생했습니다.
잠시 후 다시 시도해 주세요.

Log message:

API Error: /api/workorder/search, TimeoutException

5. API Change Rule

When changing an API:

Update this document.
Update related client code.
Update test checklist.
Keep backward compatibility if possible.


---

# 11. BUILD_GUIDE.md 샘플

빌드 방법이 정리되어 있지 않으면 Codex도 사람도 헤맵니다.

```markdown
# BUILD_GUIDE.md

## 1. Development Environment

- OS: Windows 10 or later
- IDE: Visual Studio
- Language: C#
- Framework: .NET Framework or .NET version used by the project
- Database: MariaDB
- DB Tool: HeidiSQL or DBeaver

## 2. Build Steps

1. Open the solution file in Visual Studio.
2. Restore NuGet packages.
3. Check database connection settings.
4. Build the solution.
5. Run the application.
6. Check log folder creation.

## 3. Common Build Errors

### Duplicate Assembly Attribute

Cause:

- AssemblyInfo.cs and project auto-generation both define assembly attributes.

Resolution:

- Check project settings.
- Remove duplicate attributes.
- Do not randomly delete files.

### Missing Reference

Cause:

- NuGet package missing.
- DLL reference path changed.

Resolution:

- Restore NuGet packages.
- Check HintPath.
- Confirm required DLL exists.

## 4. Release Build

Before release:

- Build in Release mode.
- Run smoke test.
- Check DB connection.
- Check log folder.
- Check main screens.
- Check version number.
- Prepare release notes.

12. TEST_GUIDE.md 샘플

테스트 기준이 없으면 “수정은 됐는데 맞는지 모르는” 상태가 됩니다.

# TEST_GUIDE.md

## 1. Test Principle

Every change must include a manual test checklist.

The goal is not only to confirm that the function works, but also to confirm that it fails safely.

## 2. Common Test Checklist

For every modified screen:

- Screen opens normally.
- Search works.
- Save works.
- Required field validation works.
- Delete confirmation works.
- DB error does not crash the application.
- Network error does not crash the application.
- Logs are created.
- Existing functions still work.

## 3. Work Order Test Scenario

1. Open 작업지시관리.
2. Search existing work orders.
3. Create a new work order.
4. Select item.
5. Select process.
6. Enter order quantity.
7. Save.
8. Confirm created data in grid.
9. Start work.
10. Enter material input.
11. End work.
12. Register production result.
13. Check stock transaction.
14. Check process history.

## 4. Error Test

- Disconnect DB and run search.
- Enter invalid date.
- Enter text into numeric field.
- Save without required fields.
- Try duplicate code.
- Delete selected data.
- Close screen during operation.

## 5. Test Result Format

```text
Test Date:
Tester:
Screen:
Result:
Issues:
Remarks:


---

# 13. RELEASE_GUIDE.md 샘플

출시 전에는 별도 기준이 있으면 좋습니다.

```markdown
# RELEASE_GUIDE.md

## 1. Release Policy

Release must be stable, traceable, and reversible.

Do not release untested code.

## 2. Version Rule

Version format:

```text
Major.Minor.Patch

Example:

1.0.13

Major: Large structural change
Minor: Feature addition
Patch: Bug fix or small improvement

3. Release Checklist

Before release:

Build success
Main screen test
DB connection test
Login test
Major function test
Error log test
Version number update
Release notes prepared
Backup existing executable
Backup DB if schema changed

4. Release Notes Format

Version:
Release Date:
Main Changes:
Bug Fixes:
Known Issues:
Upgrade Notes:

5. Rollback Rule

If a critical issue occurs:

Stop new deployment.
Restore previous executable.
Restore DB backup if needed.
Check logs.
Document the issue.


---

# 14. Codex에게 가이드 문서를 만들게 하는 프롬프트

처음부터 직접 다 쓰기 어렵다면 Codex에게 이렇게 요청하면 됩니다.

```text
이 프로젝트를 분석해서 Codex가 사용할 AGENTS.md를 만들어줘.

조건:
1. 프로젝트 구조를 먼저 파악해줘.
2. 사용 언어, 프레임워크, DB, 빌드 방식을 정리해줘.
3. 코딩 규칙, DB 변경 규칙, 예외 처리 규칙을 포함해줘.
4. 수정 금지 사항을 명확히 써줘.
5. 너무 길지 않게 실무형으로 작성해줘.
6. 필요한 경우 PROJECT_RULES.md, CODING_GUIDE.md, DESIGN_GUIDE.md로 분리해서 제안해줘.

이미 MES Lite 같은 방향이 정해져 있다면 이렇게 지시하면 좋습니다.

MES Lite 프로젝트용 AGENTS.md와 가이드 문서를 만들어줘.

환경:
- C#
- WinForms
- MariaDB
- 기존 VB6 소스 일부 참조
- 향후 C# MAUI 확장 예정
- 중소제조업용 MES
- DB는 codeM/codeD, objectM/objectD, PlanM/PlanD, ProcessM/ProcessD, stockM/stockD 구조를 활용

문서:
1. AGENTS.md
2. PROJECT_RULES.md
3. CODING_GUIDE.md
4. DESIGN_GUIDE.md
5. DB_SCHEMA.md
6. BUILD_GUIDE.md
7. TEST_GUIDE.md

각 문서는 실제 프로젝트 루트에 저장할 수 있는 Markdown 형식으로 작성해줘.

OpenAI 문서에서도 Codex CLI의 /init 명령을 사용하면 현재 디렉터리에 시작용 AGENTS.md를 만들 수 있으며, 이후 실제 팀의 빌드·테스트·리뷰 방식에 맞게 수정하는 것이 좋다고 안내합니다.

15. 가이드 문서 운영 방법

가이드 문서는 한 번 만들고 끝나는 문서가 아닙니다.

Codex가 같은 실수를 반복하면 그 내용을 문서에 추가해야 합니다.

예를 들어 Codex가 자꾸 DB 컬럼을 새로 만들려고 한다면 AGENTS.md에 이렇게 추가합니다.

Do not add new database columns without approval.
Use codeM/codeD and objectM/objectD first.
If a schema change seems necessary, propose it before implementation.

Codex가 화면 버튼을 중복 생성한다면 DESIGN_GUIDE.md에 이렇게 추가합니다.

Do not create duplicate buttons for the same action.
Before adding a button, check whether an existing button already performs the function.

Codex가 예외 처리를 빼먹는다면 CODING_GUIDE.md에 이렇게 추가합니다.

All DB and API methods must include try-catch.
Log the exception and show a user-friendly message.
The program must not terminate due to DB or network errors.

이렇게 실제 문제를 기준으로 문서를 계속 개선하면 Codex의 작업 품질이 점점 좋아집니다.

OpenAI 문서에서도 AGENTS.md는 짧고 실용적으로 유지하고, 반복되는 실수가 생기면 회고를 통해 문서를 업데이트하는 방식이 좋다고 설명합니다.

16. 폴더별 AGENTS.md 활용

프로젝트가 커지면 루트에 하나만 두는 것보다 폴더별로 추가할 수 있습니다.

예를 들면 다음과 같습니다.

MESLite
├─ AGENTS.md
├─ Forms
│  └─ AGENTS.md
├─ Database
│  └─ AGENTS.md
├─ Api
│  └─ AGENTS.md
└─ Reports
   └─ AGENTS.md

루트의 AGENTS.md는 전체 규칙을 담고, Forms/AGENTS.md는 화면 개발 규칙, Database/AGENTS.md는 DB 작업 규칙, Reports/AGENTS.md는 리포트 작업 규칙을 담는 방식입니다.

OpenAI 문서에 따르면 AGENTS.md는 전역, 저장소, 하위 디렉터리 수준으로 둘 수 있고, 더 가까운 위치의 구체적인 지침이 우선 적용될 수 있습니다.

17. 좋은 가이드 문서의 기준

좋은 가이드 문서는 다음 조건을 만족합니다.

첫째, 짧고 명확합니다.

둘째, 실제 프로젝트 기준입니다.

셋째, 금지 사항이 분명합니다.

넷째, 테스트 방법이 있습니다.

다섯째, 완료 기준이 있습니다.

여섯째, Codex가 반복적으로 실수하는 부분을 막아줍니다.

일곱째, 사람이 봐도 이해할 수 있습니다.

AI용 문서라고 해서 사람에게 불친절하면 안 됩니다. 결국 이 문서는 Codex뿐만 아니라 개발자, 내부 전산운영자, 유지보수 담당자도 함께 보는 기준 문서가 됩니다.

18. MES Lite 프로젝트용 추천 문서 세트

MES Lite 같은 업무 시스템이라면 최소한 다음 문서는 만들어두는 것이 좋습니다.

AGENTS.md
PROJECT_RULES.md
CODING_GUIDE.md
DESIGN_GUIDE.md
DB_SCHEMA.md
BUILD_GUIDE.md
TEST_GUIDE.md

조금 더 체계적으로 운영하려면 다음 문서도 추가하면 좋습니다.

API_SPEC.md
RELEASE_GUIDE.md
ERROR_HANDLING_GUIDE.md
LOGGING_GUIDE.md
SECURITY_GUIDE.md
DEPLOY_GUIDE.md
USER_MANUAL.md

특히 내부 전산운영자를 양성하려는 프로젝트라면 USER_MANUAL.md와 MAINTENANCE_GUIDE.md도 매우 중요합니다.

Codex는 개발만 하는 도구가 아닙니다. 문서 작성, 테스트 시나리오 작성, 코드 리뷰, 기능 설명, 오류 분석에도 사용할 수 있습니다. OpenAI도 Codex를 활용해 코드베이스를 요약하고 문서를 업데이트하며, 시스템 다이어그램 같은 개발 문서를 생성하는 방식이 가능하다고 설명합니다.

마무리

Codex를 잘 쓰려면 좋은 프롬프트도 중요하지만, 더 중요한 것은 좋은 프로젝트 기준 문서입니다.

AGENTS.md는 Codex에게 “이 프로젝트에서는 이렇게 일해야 한다”고 알려주는 기본 지침서입니다.

PROJECT_RULES.md는 프로젝트의 방향을 정합니다.

CODING_GUIDE.md는 코드 품질을 지킵니다.

DESIGN_GUIDE.md는 화면 일관성을 지킵니다.

DB_SCHEMA.md는 데이터 구조를 보호합니다.

BUILD_GUIDE.md와 TEST_GUIDE.md는 결과물을 검증하게 해줍니다.

AI 코딩 시대의 개발은 단순히 코드를 빨리 만드는 것이 아닙니다.

AI가 실수하지 않도록 기준을 만들고, 반복되는 작업을 표준화하고, 사람이 검토 가능한 구조로 개발하는 것이 핵심입니다.

결국 좋은 Codex 사용법은 좋은 개발 관리법과 같습니다.

문서가 좋아지면 Codex가 좋아지고, Codex가 좋아지면 개발 속도와 품질이 같이 올라갑니다.

'AI > Vibe Coding' 카테고리의 다른 글

ChatGPT Codex란? (0)	2026.07.02
AI 에이전트 개발, 가이드 문서가 먼저다 (0)	2026.06.25
[3회차] Vibe Coding 고급 (1)	2026.06.25
[2회차] Vibe Coding 중급 (0)	2026.06.25
[1회차] Vibe Coding 기초 (0)	2026.06.25

IT 만물상

Codex를 제대로 쓰기 위한 가이드 문서 만들기

AGENTS.md, PROJECT_RULES.md, CODING_GUIDE.md 샘플까지 한 번에 정리

1. AGENTS.md란?

2. 왜 AGENTS.md가 중요한가?

3. AGENTS.md와 다른 가이드 문서의 차이

4. AGENTS.md 작성 원칙

5. AGENTS.md 샘플

6. PROJECT_RULES.md 샘플

7. CODING_GUIDE.md 샘플

4. Logging Rules

5. SQL Rules

6. Validation Rules

7. Code Review Checklist

9. DB_SCHEMA.md 샘플

10. API_SPEC.md 샘플

4. Error Handling

5. API Change Rule

12. TEST_GUIDE.md 샘플

3. Release Checklist

4. Release Notes Format

5. Rollback Rule

15. 가이드 문서 운영 방법

16. 폴더별 AGENTS.md 활용

17. 좋은 가이드 문서의 기준

18. MES Lite 프로젝트용 추천 문서 세트

마무리

'AI > Vibe Coding' 카테고리의 다른 글

티스토리툴바

Codex를 제대로 쓰기 위한 가이드 문서 만들기

AGENTS.md, PROJECT_RULES.md, CODING_GUIDE.md 샘플까지 한 번에 정리

1. AGENTS.md란?

2. 왜 AGENTS.md가 중요한가?

3. AGENTS.md와 다른 가이드 문서의 차이

4. AGENTS.md 작성 원칙

5. AGENTS.md 샘플

6. PROJECT_RULES.md 샘플

7. CODING_GUIDE.md 샘플

4. Logging Rules

5. SQL Rules

6. Validation Rules

7. Code Review Checklist

9. DB_SCHEMA.md 샘플

10. API_SPEC.md 샘플

4. Error Handling

5. API Change Rule

12. TEST_GUIDE.md 샘플

3. Release Checklist

4. Release Notes Format

5. Rollback Rule

15. 가이드 문서 운영 방법

16. 폴더별 AGENTS.md 활용

17. 좋은 가이드 문서의 기준

18. MES Lite 프로젝트용 추천 문서 세트

마무리

'AI > Vibe Coding' 카테고리의 다른 글

관련글

티스토리툴바