企业官网建设流程全解析

Codex 落地实操手册

# Codex 工作区规则## 工作边界-所有文件操作限制在 `CodeXWorkPlace/` 目录内-禁止修改外部系统文件## 项目命名-格式：`project_三位序号_简称`-例：`project_001_fpca_detect`-序号永久递增，废弃项目也不复用## 项目强制结构每个项目必须包含：-README.md（目标、技术栈、运行方式）-requirements.txt（依赖）-src/（源码）-tests/（测试）-docs/（设计文档）-.codex_history（本项目专属对话摘要）## 全局日志-路径：`logs/global_log.md`-每次对话结束，追加记录：本次任务、关键决策、代码变更、遗留问题、下次计划## 上下文管理-每次新对话先读取 `.codex_history`-单文件超过500行时拆分模块，并在 `.codex_history` 记录## 版本控制-工作区已初始化 Git-每完成一个功能点：gitadd+commit-提交格式：`[project_xxx]feat/fix/refactor:描述`## 开发流程1.需求阶段：先写 `docs/PRD.md`，只审阅不编码2.设计阶段：输出 `docs/design.md`，确认后再编码3.编码阶段：按模块输出，每模块附自测用例4.审查阶段：检查边界情况、性能、内存泄漏5.归档阶段：项目完结后整理 `project_retrospective.md` 存入 `archive/`## 高频指令识别用户说"启动新项目"→ 先创建 README.md 和 design.md 用户说"续写旧项目"→ 先读取.codex_history 和 global_log.md 最后3条 用户说"记录日志"→ 追加到 global_log.md 用户说"审查"→ 检查边界、性能、是否符合.codex_history 约束

CodeX 落地实操手册 v2.0

一、工作区创建（CodeXWorkPlace）

实操步骤：

1. 在 IDE / 编辑器根目录创建文件夹CodeXWorkPlace
2. 首次启动时，明确指令：“所有操作限制在 CodeXWorkPlace 目录内，禁止修改外部文件”
3. 子目录按功能划分：

   CodeXWorkPlace/ ├── projects/ # 项目代码 ├── logs/ # 全局日志 ├── docs/ # 需求文档 & 设计文档 ├── snippets/ # 可复用代码片段 └── archive/ # 废弃/归档项目

在这里插入代码片

关键约束：每次对话开头重申工作区路径，防止 Codex “越界” 修改系统文件。

二、全局日志系统（Global Log）

实操步骤：

1. 在CodeXWorkPlace/logs/下创建global_log.md
2. 强制要求 Codex每次对话结束后追加记录，格式如下：

## Log: YYYY-MM-DD HH:MM ### 本次任务 - 需求描述：[一句话概括] - 关联项目：[project_001 / 无] ### 关键决策 - 采用方案：[A/B/C 及理由] - 放弃方案：[及理由] ### 代码变更 - 新增文件：`projects/project_001/src/main.py` - 修改文件：`projects/project_001/config.yaml` - 关键函数：`calculate_fpca()` 增加异常处理 ### 遗留问题 - [ ] 边界情况未测试：空输入处理 - [ ] 性能优化：当前 O(n²)，需评估是否优化 ### 下次计划 - 完成单元测试覆盖

关键约束：日志由 Codex 自动写，你在每次对话结束时说“把本次内容记录到全局日志”，养成肌肉记忆。

三、项目命名规范（project_序号）

实操步骤：

1. 命名格式：project_三位序号_项目简称
   • 例：project_001_fpca_detect、project_002_vit_tutorial
2. 每个项目内部强制结构：

   project_001_fpca_detect/ ├── README.md # 项目目标、技术栈、运行方式 ├── requirements.txt # 依赖 ├── src/ # 源码 ├── tests/ # 测试 ├── docs/ # 设计文档 └── .codex_history # 本项目专属对话摘要

3. 序号永久递增，即使项目废弃也不复用，保证日志可追溯。

四、上下文管理（新增）

问题：Codex 上下文有限，长项目会"失忆"。

实操步骤：

1. 每个项目创建.codex_history文件，记录：
   • 已确认的需求（防止 Codex 反复修改）
   • 已确定的技术选型（防止反复切换框架）
   • 已知的 Bug 和 workaround
2. 每次新对话先投喂历史：“请先阅读project_001/.codex_history，本次需求是…”
3. 单文件超过 500 行时，要求 Codex拆分模块，并在.codex_history中记录模块职责。

五、版本控制（新增）

实操步骤：

1. 在CodeXWorkPlace初始化 Git：

   gitinitecho"logs/">>.gitignore# 日志可能含敏感信息

2. 设定提交节点：
   • 每完成一个功能点：让 Codex 执行git add + commit，提交信息由 Codex 按规范写
   • 重大重构前：强制 Codex 先提交当前状态，再开始修改
3. 提交信息规范：

   [project_001] feat: 增加 FPCA 特征提取 [project_001] fix: 修复空输入崩溃 [project_001] refactor: 将 utils 拆分为 math_utils 和 io_utils

六、需求 → 代码审查流程（新增）

实操步骤：

1. 需求阶段：先在docs/写PRD.md（产品需求文档），让 Codex 只审阅不编码
2. 设计阶段：让 Codex 输出design.md（技术方案），你确认后再编码
3. 编码阶段：要求 Codex 按模块输出，每模块附自测用例
4. 审查阶段：代码完成后，强制提问：
   • “这段代码的边界情况是什么？”
   • “有没有内存泄漏 / 性能瓶颈？”
   • “是否符合项目.codex_history中的技术约束？”
5. 归档阶段：项目完结后，Codex 整理project_retrospective.md存入archive/

七、高频指令模板（新增）

直接复制使用：

八、避坑清单（新增）

1. 不要让 Codex 直接修改生产环境代码，必须通过tests/验证
2. 不要在同一个对话中切换项目，容易污染上下文
3. 不要让日志只记录成功，失败和放弃的方案更有价值
4. 不要让 Codex 自动生成序号，你自己管控project_xxx的递增，防止重复

这套流程的核心是“把 Codex 当实习生管理”：给它明确的工作边界（工作区）、要求它写日报（日志）、规范它的项目命名、强制它先交方案再干活、重要节点留档（Git）。这样 Codex 的产出质量会稳定很多，且三个月后你仍能看懂当时为什么那么写。