文档更新

Project/fonrey/Vibe Coding项目管理技巧.md

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