这是一个非常实际的问题。用 OpenCode（或类似 AI 编码工具）做长周期项目，核心挑战是**每次会话 AI 都是"失忆"的**，你需要一套机制让它快速恢复上下文。

以下是一套完整的项目管理方案：

---

## 核心思路：用文档作为 AI 的"外部记忆"

AI 没有跨会话记忆，但它每次都能读文件。所以你的目标是：**把项目状态写进文件，而不是靠 AI 记住。**

---

## 一、项目文档结构

在项目根目录维护以下几个关键文件：

```
project-root/
├── CLAUDE.md          # AI 行为规则 + 项目概览（OpenCode 每次自动读取）
├── TASK.md            # 任务总表，P0/P1/P2 优先级
├── PROGRESS.md        # 每日进度日志（最重要）
├── ARCHITECTURE.md    # 技术架构
└── .opencode/
    └── context.md     # 会话级补充上下文（可选）
```

---

## 二、最关键的文件：`PROGRESS.md`

这是你每天结束时必须更新的文件，格式建议如下：

```markdown
# 项目进度日志

## 2025-01-15（今日）

### ✅ 已完成
- [x] 实现了 PropertyListing 的 CRUD API
- [x] 修复了权限校验的 bug（见 commit abc123）

### 🔄 进行中
- [ ] 房源搜索功能（已完成 70%）
  - 已做：Elasticsearch 索引配置
  - 未做：前端搜索组件、过滤器逻辑
  - 卡点：全文搜索中文分词需要引入 IK 插件

### ⏭️ 明日计划
- 完成搜索前端组件
- 开始客源管理模块的数据模型

### 🐛 已知问题 / 技术债
- PropertyImage 上传后缩略图生成有时失败，原因未查

### 📁 今日改动的关键文件
- `apps/listings/views.py`
- `apps/listings/serializers.py`
- `templates/listings/search.html`
```

---

## 三、`CLAUDE.md` — AI 的启动说明书

OpenCode 会自动读取项目根目录的 `CLAUDE.md`。把它写成"给 AI 的操作手册"：

```markdown
# Fonrey 项目 AI 开发规范

## 项目简介
B2B SaaS 房产中介管理系统，Django + HTMX + Alpine.js + PostgreSQL

## 每次会话开始前，你必须做的事
1. 阅读 `PROGRESS.md` 了解当前进度
2. 阅读 `TASK.md` 了解当前 Sprint 目标
3. 确认今天要完成哪个具体任务后再写代码

## 技术约束
- 前端：HTMX + Alpine.js + Tailwind，禁止引入 React/Vue
- 文件上传：统一用 FilePond
- 权限：使用自定义 RBAC，不使用 django-guardian

## 代码规范
- 所有新文件必须有注释说明用途
- 每完成一个功能，更新 PROGRESS.md

## 禁止事项
- 不要修改 DATA_MODEL.md 中已定稳的数据表结构
- 不要在没有确认的情况下重构已有模块
```

---

## 四、每日工作流程

### 早上开始（2 分钟）

给 AI 发这条固定的"启动 prompt"：

```
请阅读 PROGRESS.md 和 TASK.md，告诉我：
1. 昨天完成了什么
2. 今天应该继续做什么
3. 有没有未解决的卡点

然后我们开始今天的工作。
```

AI 读完文件后会给你一个摘要，你确认后直接开工。

### 晚上结束（5 分钟）

让 AI 帮你更新进度日志：

```
今天的工作完成了，请帮我更新 PROGRESS.md：
- 完成了：[你说]
- 未完成的：[你说]  
- 明天继续：[你说]
```

---

## 五、处理"卡点"和"上下文切换"

### 当你在一个功能里遇到复杂问题时

创建一个临时文件 `SCRATCH.md`：

```markdown
# 当前卡点：中文全文搜索

## 问题描述
PostgreSQL tsvector 对中文分词支持差

## 已尝试的方案
1. 方案A：用 zhparser - 失败，原因 xxx
2. 方案B：用 pg_jieba - 待验证

## 当前倾向
方案B，明天继续
```

下次会话告诉 AI："先读 SCRATCH.md"，秒回上下文。

### 当你需要切换模块时

在 PROGRESS.md 里明确标记"暂停点"，记录文件名和函数名，这比描述更精确。

---

## 六、可选增强：Git commit 作为进度锚点

养成每完成一个小功能就 commit 的习惯，commit message 写清楚：

```
feat(listings): 完成房源搜索 API，支持关键词+区域过滤

TODO: 前端搜索组件待完成
```

这样 AI 可以通过 `git log --oneline -20` 快速看到最近的工作轨迹，作为 PROGRESS.md 的补充。

---

## 总结

|文件|作用|更新频率|
|---|---|---|
|`CLAUDE.md`|AI 行为规范，一次写好|很少改|
|`TASK.md`|任务总表|每周调整|
|`PROGRESS.md`|每日进度日志|**每天必更新**|
|`SCRATCH.md`|当前卡点临时笔记|按需|

**最核心的一句话：每天花 5 分钟更新 `PROGRESS.md`，比什么方法都有效。** AI 能读文件，但它读不了你的脑子——把脑子里的状态写进文件，问题就解决了。