AI 相關紀錄 v1｜Claude Code / Codex CLI 初始化與基本概念

這個系列主要記錄目前我正在學習與實際使用的 AI 相關內容。

這篇先從 Claude Code 與 Codex CLI 開始，整理一開始比較容易搞混的幾個概念：

• CLI 是什麼？
• Coding Agent 跟一般網頁聊天有什麼不同？
• AI 是怎麼知道專案內容的？
• Context 是什麼？
• Agent 是什麼？
• /init 做了什麼？
• CLAUDE.md 與 AGENTS.md 又是什麼？

這裡主要是我目前學習與實際使用後的整理紀錄。AI 工具更新速度很快，如果後續功能或使用方式有所改變，也會再持續調整。

本文主要會使用以下工具與名稱：

關於 SDD

SDD 全名：

Spec-Driven Development
規格驅動開發

可以先簡單理解成：

在讓 AI 開始寫程式之前，先把「要做什麼」整理清楚，再進一步產生實作計畫與可以執行的工作項目。

以 GitHub Spec Kit 的核心 SDD 流程為例，可以簡化成：

Spec
定義需求
  ↓
Plan
規劃怎麼做
  ↓
Tasks
拆成可以執行的任務
  ↓
Implement
開始進行實作

也就是先處理：

我要做什麼？
↓
打算怎麼做？
↓
需要完成哪些事情？
↓
開始實作

SDD 並不是使用 Claude Code 或 Codex CLI 的必要條件，而是一種讓 AI Coding 開發流程更有結構的方法。

這部分之後再另外整理實際使用方式。

軟體環境

這篇主要以我目前實際使用的開發環境進行紀錄。

• 編輯器：Visual Studio Code
• Node.js：JavaScript 執行環境
• npm：Node.js 套件管理工具
• Terminal：用來透過命令列操作 Claude Code / Codex CLI

以上主要記錄我自己的使用環境，不代表只能使用上述工具。

Claude Code / Codex CLI 的實際支援環境與安裝方式，仍以官方文件為準。

Claude Code / Codex CLI 初始化

這部分紀錄如何在既有專案中開始使用 Claude Code / Codex CLI，以及一開始比較容易遇到的幾個基本概念。

這些 AI Coding 工具到底是怎麼進入專案、理解專案，並開始工作的？

CLI 是什麼？

CLI 全名：

CLI = Command Line Interface
    = 命令列介面

簡單來說，就是透過 Terminal 輸入指令操作程式，而不是使用一般網頁上的按鈕或圖形介面。

例如啟動 Claude Code：

claude

啟動 Codex CLI：

codex

Claude Code / Codex CLI 跟網頁版 AI 差在哪？

在一般網頁聊天情境下，如果 AI 無法直接存取本機專案，通常需要由使用者提供程式碼、檔案或其他相關 Context。

例如：

使用者提供程式碼 / 檔案
        ↓
AI 讀取內容
        ↓
AI 分析並回答

如果 AI 不知道其他檔案的內容，就需要再提供程式碼、上傳檔案，或補充相關資訊。

Claude Code、Codex CLI 這類 Coding Agent 則可以直接在被允許的專案工作環境中使用工具。

例如：

專案
  ↓
Claude Code / Codex CLI
  ↓
搜尋需要的檔案
  ↓
讀取程式碼
  ↓
分析問題
  ↓
需要時修改檔案 / 執行指令

最大的差異之一，是 Claude Code / Codex CLI 可以直接在開發環境中工作，並主動尋找完成目前任務所需要的資訊。

AI 是怎麼知道我的專案內容的？

假設在某個專案目錄中啟動 Coding Agent：

在某個專案目錄啟動 AI
          ↓
知道目前所在的工作目錄
          ↓
根據任務搜尋需要的檔案
          ↓
讀取相關內容
          ↓
逐步建立對目前任務與專案的理解

它並不是一開始就把整個專案全部「記住」。

範例

假設專案結構是：

my-project/
├─ package.json
├─ nuxt.config.ts
├─ components/
├─ pages/
├─ composables/
├─ server/
└─ ...

使用者告訴 AI：

幫我看看登入功能在哪。

AI 可能會先搜尋：

login
auth
signin
oauth

找到相關內容後，再進一步查看：

pages/login.vue
composables/useAuth.ts
server/api/login.ts
nuxt.config.ts

也就是：

收到任務
↓
搜尋可能相關的內容
↓
找到相關檔案
↓
讀取需要的程式碼
↓
繼續分析

Coding Agent 不需要一開始就把整個專案全部塞進 Context，而是可以透過工具逐步尋找完成任務所需要的資訊。

這些被讀取的資訊，會成為 AI 處理目前任務時所使用的 Context。

Context 是什麼？

可以先簡單理解成：

AI 目前用來理解這次任務的資訊。

例如：

Context
│
├─ 目前的對話內容
│
├─ AI 已經讀取的程式碼
│
├─ 搜尋得到的資訊
│
├─ 工具執行結果
│
├─ 專案指示
│   ├─ CLAUDE.md
│   └─ AGENTS.md
│
└─ 其他與目前任務相關的資訊

其中：

Claude Code → CLAUDE.md

Codex CLI → AGENTS.md

這些檔案可以提供比較持續性的專案工作指示。

但要注意：

CLAUDE.md / AGENTS.md 是 Context 的來源之一，不等於 Context 本身。

AI 可以讀什麼、修改什麼？

Claude Code / Codex CLI 並不是只能回答程式問題。

它們在被允許的環境中，可以使用不同工具完成工作。

          Claude Code / Codex CLI
                    │
          ┌─────────┼─────────┐
          ↓         ↓         ↓
        讀檔案     改檔案     執行指令

例如可能會：

查看 package.json

搜尋某個 function

讀取 Vue Component

新增檔案

修改程式碼

執行 npm test

執行 npm run build

查看 git diff

不過：

AI 具備操作工具的能力，不代表所有操作都能直接執行。

實際可以操作到什麼程度，還會受到：

Permission
Sandbox
Approval
Settings

等權限與環境設定影響。

這部分會在後續紀錄中另外整理。

所謂 Agent 到底是什麼？

一般 AI 聊天的流程比較像：

你：這段程式碼哪裡錯？

AI：
分析
↓
回答

但 Agent 的工作方式可能會變成：

你：
幫我找出為什麼登入會失敗

AI：

搜尋專案
↓
找到登入相關程式碼
↓
讀取檔案
↓
找到相關 API
↓
查看設定
↓
判斷問題
↓
修改程式
↓
執行測試
↓
查看測試結果
↓
如果仍有問題繼續修正
↓
再次驗證

Agent 不只是「回答問題」，而是可以為了完成任務使用工具、觀察執行結果，並根據目前狀況決定下一步要做什麼。

可以先簡化理解成：

LLM 提供推理與生成能力，而 Agent 系統在 LLM 之外，再結合 Tools、Context 與執行流程，讓 AI 不只回答問題，也可以採取行動完成任務。

              Agent
                │
        ┌───────┼───────┐
        ↓       ↓       ↓
       LLM     Tools   Context
        │       │        │
      推理     讀檔      對話
      判斷     搜尋      程式碼
      生成     改檔      專案指示
               Shell     執行結果

這裡先把 Agent 理解成：

模型
+
工具
+
Context
+
執行流程

即可。

在既有專案中啟動 Claude Code / Codex CLI

開始前需要先安裝 Claude Code 或 Codex CLI，並登入對應帳號。

完整安裝方式可以參考官方文件，這裡只記錄我自己實際使用的 npm 安裝方式。

• Claude Code 官方文件
• Codex CLI 官方文件

Claude Code 官方也提供 Native Installer 等其他安裝方式，並較推薦使用 Native Installer；本文只記錄我自己實際使用的 npm 方式。

安裝

如果本機已經安裝 Node.js 與 npm，可以透過 npm 進行全域安裝。

先簡單認識：

Node.js
→ JavaScript 執行環境

npm
→ Node.js 套件管理工具

nvm
→ Node.js 版本管理工具

Claude Code 安裝指令

npm install -g @anthropic-ai/claude-code

npm：

@anthropic-ai/claude-code

Codex CLI 安裝指令

npm install -g @openai/codex

npm：

@openai/codex

安裝完成後可以先檢查版本：

claude --version
codex --version

也可以查看 CLI 提供哪些參數：

claude --help
codex --help

Claude Code

先進入專案：

cd my-project

啟動 Claude Code：

claude

第一次使用時依照畫面指示完成登入後，就可以開始使用。

進入專案
↓
啟動 claude
↓
完成登入
↓
開始使用 Claude Code

Codex CLI

先進入專案：

cd my-project

啟動 Codex CLI：

codex

第一次使用時依照畫面指示完成登入。

進入專案
↓
啟動 codex
↓
完成登入
↓
開始使用 Codex CLI

第一次進入專案需要 /init 嗎？

不一定。

即使沒有執行 /init，Coding Agent 仍然可以依照目前的任務搜尋、讀取與理解專案內容。

/init 比較重要的用途是：

替目前專案建立一份之後工作時可以持續參考的專案指示。

也就是：

沒有 /init

AI
↓
還是可以搜尋專案
↓
讀取程式碼
↓
完成任務

但執行 /init 後，可以多一份：

專案工作指示

讓 Coding Agent 之後進入專案工作時，可以取得一些應該持續知道的資訊。

Claude Code 的 /init 做了什麼？

在 Claude Code 中執行：

/init

Claude Code 會分析目前的 Codebase，並建立一份起始的：

CLAUDE.md

流程可以簡化成：

分析目前專案
↓
整理重要資訊
↓
建立 / 改善 CLAUDE.md
↓
讓之後的 Claude Code Session
可以取得持續性的專案工作指示

如果原本已經存在 CLAUDE.md，則會以分析與改善現有內容為主，而不是單純把原本的檔案覆蓋掉。

CLAUDE.md 是什麼？

CLAUDE.md 是提供 Claude Code 使用的持續性專案指示文件。

它的用途不是把整份專案文件全部塞進去，而是記錄：

• 專案架構的重要資訊
• Build / Test 指令
• Coding Convention
• 使用的套件管理工具
• 重要開發流程
• AI 容易弄錯，但每次工作都應該知道的規則

可以用一個問題來判斷：

如果今天有一個新的工程師加入專案，有哪些事情是他在開始工作前最好先知道的？

這些資訊通常就是很適合整理進 CLAUDE.md 的內容。

簡單範例

# 專案

## 技術

## 常用指令

## 開發規則

後續會再另外整理 CLAUDE.md 實際可以怎麼寫。

Codex CLI 的 /init 做了什麼？

在 Codex CLI 中執行：

/init

Codex 可以為目前專案建立：

AGENTS.md

流程可以先簡化成：

分析 / 理解目前專案
↓
建立 AGENTS.md
↓
記錄專案工作指示
↓
Codex 後續工作時使用

AGENTS.md 是什麼？

AGENTS.md 是 Codex 使用的專案指示文件。

可以記錄：

• 專案架構
• 開發規範
• 常用指令
• 測試方式
• Coding Style
• 需要避免的操作
• 專案特殊限制

容易搞混的一點是：

AGENTS.md 雖然名字裡有 Agent，但它並不是用來「建立一個 Agent」的檔案。

在這裡可以先把它理解成：

Codex Coding Agent 的專案工作說明書。

簡單範例

# 專案

## 技術

## 常用指令

## 開發規則

後續也會再另外整理 AGENTS.md 可以怎麼使用。

初始化前後的專案差異

如果同一個專案分別使用 Claude Code 與 Codex CLI 執行 /init，專案中可能會同時存在：

my-project/
├─ CLAUDE.md     // Claude Code 使用
├─ AGENTS.md     // Codex CLI 使用
├─ package.json
├─ nuxt.config.ts
├─ components/
├─ pages/
└─ server/

要注意：

Claude Code /init
↓
CLAUDE.md

Codex CLI /init
↓
AGENTS.md

並不是執行一次 /init 就會同時產生兩個檔案。

它們的共同目的，可以先理解成：

持續告訴 Coding Agent：「這個專案應該怎麼工作。」

小結

這篇先整理幾個最基本的概念。

CLI
↓
在 Terminal 中透過命令列操作程式

Claude Code / Codex CLI
↓
可以直接在開發環境工作的 Coding Agent

Agent
↓
不只回答問題
也可以使用工具執行任務

Context
↓
AI 目前理解與處理任務所使用的資訊

CLAUDE.md
↓
Claude Code 的持續性專案指示

AGENTS.md
↓
Codex CLI 的持續性專案指示

整體流程可以先理解成：

進入專案
↓
啟動 Coding Agent
↓
Agent 根據任務搜尋與理解專案
↓
使用 /init 建立專案指示
↓
檢查並調整 CLAUDE.md / AGENTS.md
↓
開始進行實際開發任務

第一次使用不需要急著把所有 AI Coding 相關功能都學完。

目前先搞懂：

CLI
Agent
Context
/init
CLAUDE.md
AGENTS.md

這幾個概念，就已經足夠開始讓 Claude Code / Codex CLI 進入專案工作。

後續再繼續整理：

CLAUDE.md / AGENTS.md
Settings / Config
Rules
Skills
Agent / Subagent
MCP

等相關功能。