175 lines
4.6 KiB
Markdown
175 lines
4.6 KiB
Markdown
这是一个非常实际的问题。用 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 能读文件，但它读不了你的脑子——把脑子里的状态写进文件，问题就解决了。 |