workspace-guide

name	workspace-guide
description	当需要管理当前工作空间与任务流时，必须立刻阅读我。适用于编程、教学、查资料、分析、写计划、归档结果等场景；我会约束你优先用 Git 管理项目、优先使用项目原生工具链，并保持清晰的计划、产物和归档结构。

Workspace Guide

核心原则

• 这不是只会写代码的工具人，任务也可能是教学、查资料、分析、规划、归档。
• 先判断任务类型，再决定要不要克隆项目、安装依赖或修改代码。
• 新任务优先在当前工作区内使用独立目录，不要把多个任务混在一起。
• 不要随意改用户已有仓库；先看状态，再决定是否继续。
• 优先尊重项目原生工具链，不要自己发明安装方式。
• 缺依赖时再补，不要无意义重复安装。

目录约定

• <workspace> 只是占位符，不是固定目录名；它表示你当前 shell 的启动工作空间。
• 你只能在这个工作空间内工作；不要假设或访问工作空间外路径。
• 代码项目建议放到 <workspace>/projects/。
• 临时实验建议放到 <workspace>/scratch/。
• 计划建议放到 <workspace>/plan/。
• 输出文件、截图、导出物建议放到 <workspace>/artifacts/。
• 可归档结果建议放到 <workspace>/archive/。
• 不要把杂项文件直接堆在根目录。

任务分流

• 编程任务：先看仓库结构、依赖、命令，再修改代码。
• 教学任务：先明确对象、目标、难度，再组织讲解。
• 查资料任务：先明确主题、时间范围、来源要求，再检索。
• 分析任务：先定义问题、证据、结论、不确定项。
• 计划任务：先写目标、范围、步骤、风险、产出。
• 归档任务：先整理结果，再存放到固定位置并说明用途。

Git 规则

• 涉及代码项目时，优先用 Git 管理。
• 开始前先看仓库状态。
• 优先 git clone 到独立目录，再开始修改。
• 修改前先看当前分支、未提交变更、远程信息。
• 不要随意覆盖、回退、清空已有改动。
• 多任务并行时，尽量一任务一目录。

工具链偏好

• Python 优先 uv。
• Node.js 优先 pnpm。
• Rust 优先 cargo。
• 如果项目已经明确使用别的工具链，优先遵循项目约定。
• 全局安装越少越好，优先项目内依赖。

进入项目先做什么

1. 先读 README、package.json、pyproject.toml、Cargo.toml 等关键文件。
2. 判断项目使用什么语言、包管理器、构建方式、测试方式。
3. 先确认启动、测试、格式化命令，再开始改动。
4. 查不到就继续搜索，不要猜。

Plan

• 需要计划时，先写目标、范围、步骤、风险、交付物。
• 步骤尽量短，能执行、能检查、能更新状态。
• 计划文件建议放到 <workspace>/plan/。
• 不要把计划写成空话，要能直接指导下一步动作。

Archive

• 结果可复用时，主动整理并归档。
• 归档内容可以是总结、报告、导出文件、截图、链接清单、交付说明。
• 归档前先说明内容是什么、为什么保留、后续怎么找。
• 归档文件建议放到 <workspace>/archive/ 或 <workspace>/artifacts/。

临时文件与产物

• 调试脚本、下载物、截图、导出文件放到约定目录。
• 不要把临时文件混进源码目录。
• 完成后说明产物放在哪里。

交付前自检

• 看是否真的完成了当前任务类型，而不是只完成了代码修改。
• 看 diff、结果、引用资料或计划内容是否匹配目标。
• 跑最小验证。
• 确认没有误改无关文件。
• 汇报做了什么、怎么验证、还有什么未完成。