AGENTS.md Introductory Handout: Simple Project Rules for Codex

Goals of This Handout

AGENTS.md is a text file placed at the top level of a Codex project. Its purpose is simple: tell Codex how it should work in this project.

This handout focuses only on the simplest Codex project. Assume your project contains only the files you are currently working on, and the goal is to give Codex a few basic working rules.

What AGENTS.md Is

When you open a project with Codex, Codex can read, create, or edit files inside that project. AGENTS.md is the project rule file written for Codex.

It can describe:

• What this project is for.
• What tone Codex should use when replying.
• What Codex should watch for when editing files.
• Which actions require asking the user first.
• How Codex should check the work after finishing.

AGENTS.md does not need to be long. Any rule that helps Codex guess less is useful.

The Simplest Codex AGENTS.md

Here is a very simple version. It only describes how Codex should work in the current project.

# AGENTS.md

## 專案

這是一個簡單的 Codex project。

## 語言

- 預設使用繁體中文。
- 使用清楚、適合初學者的說明。

## 工作規則

- 編輯前先閱讀相關檔案。
- 做小範圍、聚焦的修改。
- 除非使用者要求，不要重寫整份檔案。
- 除非使用者明確要求，不要刪除檔案。
- 進行大範圍修改前先詢問使用者。

## 輸出

- 除非使用者指定其他位置，新檔案都放在這個 project 資料夾。
- 使用清楚的檔名。
- 完成後說明修改了什麼。

## 驗證

- 檢查編輯或新增的檔案是否存在。
- 檢查內容是否符合使用者的要求。
- 如果有無法檢查的項目，要告訴使用者。

# AGENTS.md

## Project

This is a simple Codex project.

## Language

- Use Traditional Chinese by default.
- Use clear and beginner-friendly wording.

## Working Rules

- Read the relevant file before editing it.
- Make small and focused changes.
- Do not rewrite the whole file unless the user asks.
- Do not delete files unless the user clearly asks.
- Ask before making broad changes.

## Output

- Keep new files in this project folder unless the user asks for another location.
- Use clear filenames.
- Explain what changed after finishing.

## Verification

- Check that edited or created files exist.
- Check that the content matches the user's request.
- Tell the user if something could not be checked.

These rules fit most practice tasks. The point is not to restrict Codex; the point is to tell Codex to read files first, keep edits small, avoid deleting things casually, and report back after finishing.

How You Can Modify It

You can adjust the rules above to fit your own project. For example:

• If you want Codex to always use Traditional Chinese, keep Use Traditional Chinese by default.
• If you do not want Codex to rewrite a whole article, keep Do not rewrite the whole file unless the user asks.
• If this is only a short practice task, keep the rules within about 20 lines.

Do not write too many rules at the beginning. The more rules you add, the harder they are to read and maintain.

Example 1: Simple Text Editing Project

This example fits a project with only one or two text files, such as revising a script, editing explanatory text, or organizing class notes.

# AGENTS.md

## 專案

這是一個簡單的文字修改專案。

## 語言

- 使用繁體中文。
- 文字要清楚自然。
- 避免太正式或太技術性的說法。

## 工作規則

- 編輯前先閱讀檔案。
- 除非使用者要求改變，否則保留原本意思。
- 做聚焦的修改。
- 除非範例明顯無關，否則不要移除範例。

## 驗證

- 檢查修改後的文字是否容易閱讀。
- 檢查標題和清單是否仍然合理。
- 編輯後摘要主要變更。

# AGENTS.md

## Project

This is a simple writing project.

## Language

- Use Traditional Chinese.
- Keep the wording clear and natural.
- Avoid overly formal or technical language.

## Working Rules

- Read the file before editing it.
- Keep the original meaning unless the user asks to change it.
- Make focused edits.
- Do not remove examples unless they are clearly unrelated.

## Verification

- Check that the revised text is readable.
- Check that headings and lists still make sense.
- Summarize the main changes after editing.

Example 2: Simple Programming Practice Project

This example fits a small programming practice project, such as one Python file, one JavaScript file, or a simple web page.

# AGENTS.md

## 專案

這是一個小型程式練習專案。

## 語言

- 用繁體中文說明修改內容。
- 程式註解要短而有用。

## 工作規則

- 修改前先閱讀現有程式碼。
- 優先使用初學者能理解的簡單程式碼。
- 除非使用者要求，不要新增套件。
- 不要修改無關的程式碼。

## 驗證

- 可以的話，執行基本檢查。
- 如果程式無法執行，說明原因。
- 回報修改的檔案和已檢查的項目。

# AGENTS.md

## Project

This is a small coding practice project.

## Language

- Explain changes in Traditional Chinese.
- Keep code comments short and useful.

## Working Rules

- Read the existing code before changing it.
- Prefer simple code that beginners can understand.
- Do not add new libraries unless the user asks.
- Do not change unrelated code.

## Verification

- Run a basic check when possible.
- If the code cannot be run, explain why.
- Report the changed file and what was checked.

Example 3: Simple Data Organization Project

This example fits a small data file, such as cleaning a CSV, spreadsheet content, or a pasted roster.

# AGENTS.md

## 專案

這是一個簡單的資料整理專案。

## 語言

- 使用繁體中文。
- 清楚說明假設。

## 工作規則

- 不要編造缺少的資料。
- 不要暴露私人個人資料。
- 保留原始資料的意思。
- 大量更動列或欄之前先詢問。

## 驗證

- 可以的話，檢查資料列數。
- 檢查重要欄位是否仍然存在。
- 摘要缺少或異常的值。

# AGENTS.md

## Project

This is a simple data cleanup project.

## Language

- Use Traditional Chinese.
- Explain assumptions clearly.

## Working Rules

- Do not invent missing data.
- Do not expose private personal information.
- Keep the original data meaning.
- Ask before changing many rows or columns.

## Verification

- Check the number of rows if possible.
- Check that important columns are still present.
- Summarize any missing or unusual values.

Class Practice: Create Your Own AGENTS.md

Problem Statement

Create a simple AGENTS.md at the top level of your Codex project. This file only needs to describe the basic working rules for this project. It does not need to plan other folders or become a full technical document.

MVP Requirements

• Create AGENTS.md.
• State what this project is for.
• State which language Codex should use when replying.
• Write 3 to 5 working rules.
• Write 2 to 3 ways to check the work after finishing.

Suggested Prompt

You can say this directly to Codex:

為這個 Codex project 建立一份簡單的 AGENTS.md。
保持適合初學者。
使用繁體中文說明。
只聚焦在這個簡單的 Codex project。

Create a simple AGENTS.md for this Codex project.
Keep it beginner-friendly.
Use Traditional Chinese explanations.
Focus only on this simple Codex project.

Checklist

After finishing, check that your AGENTS.md:

• Is placed at the top level of the current Codex project.
• Uses short and clear rules.
• Focuses on this Codex project.
• Does not include accounts, passwords, or private information.
• Explains how Codex should check and report after finishing.

Difference Between AGENTS.md and Skills

AGENTS.md is the working rule file for this project. It answers: "How should Codex work inside this project?"

A Skill is a reusable task workflow. It answers: "When this type of task appears, what steps should Codex follow?"

Learn to write AGENTS.md first. When a task keeps repeating, then consider turning it into a Skill.