📦 Workspace Files Organization — 工作空间文件组织

工作空间文件组织 组织新的工作，使项目特定的文件保持在一起，可重用的实用程序保持分离，输出与产生它们的工作保持在一起。 强制触发器 在创建任何持久的工作空间文件或文件夹之前，停止并对其进行分类： 如果它属于特定的主题、目标、监控、cron 作业、报告、调查或自动化，创建/使用 projects//。 如果它是项目状态、缓存、输出、下载的数据、生成的内容或监控状态，将其放在 projects//data/ 下。 仅在以下情况下跳过此技能：临时 shell 输出不写入磁盘，或者明显的工作空间范围内的文件，例如 MEMORY.md、AGENTS.md、USER.md、SOUL.md 或 TOOLS.md。 具有持久状态的监控是一个项目。 具有文件的 cron 后台工作流是一个项目。 创建可重用笔记或输出的一次性调查通常是一个项目。 核心规则 将属于特定项目的所有文件放在 projects// 下，当该工作有自己的主题、目标或上下文时。 将代码、笔记、配置、提示、支持资产和该项目的输出视为项目本地，除非有强烈的理由不这样做。 将项目输出放在 projects//data/ 下。 不要创建或使用全局 data/ 目录。 仅将真正的通用、可重用的实用程序放在 scripts/ 中，不要将项目特定的脚本放在 scripts/ 中。 将每个需要创建文件的工作视为项目，从一开始就创建或选择 projects//。 不要在临时位置创建项目文件，打算稍后组织它们。 新项目文件夹标准 创建新项目文件夹时，创建： projects//README.md 立即添加一个简短的 README，包括： 项目的内容 项目开始时间 关于当前目的或范围的简要说明 除非用户要求更多详细信息，否则保持 README 简短。 推荐布局 默认情况下使用此布局进行项目特定的工作： projects/ / README.md data/ ...项目文件... 可能的项目文件包括： 脚本和代码 笔记本 提示 配置文件 抓取或下载的输入 生成的输出 摘要或笔记 仅在额外的子文件夹可以提高清晰度时才添加它们。 放置启发式 按以下顺序选择位置： 当工作需要创建持久文件时，从创建或选择 projects// 开始。 如果文件属于该项目，将其放在 projects// 下。 如果它是由该项目生成的状态、缓存或输出，将其放在 projects//data/ 下。 如果它是一个可重用的实用程序，明显可以跨不同项目使用，将其放在 scripts/ 中。 如果存在模糊性，优先创建新的项目文件夹，而不是将文件放在工作空间根目录、自定义顶级文件夹或 scripts/ 中。 根目录纪律 避免直接将新项目文件放在工作空间根目录中。 仅允许将真正的工作空间范围内的文件放在根目录中，例如： 顶级工作空间文档 共享代理笔记 在根目录中预期的全局配置 命名指导 使用简短、描述性的项目名称。 优先使用小写名称。 在工作空间内一致地使用连字符或下划线。 按域或结果命名项目，例如 dges-crawl、invoice-reconciliation 或 travel-planning。 迁移指导 当您在根目录或 scripts/ 中找到分散的项目特定文件时： 将它们分组到新的或现有的 projects// 下 将输出移到 projects//data/ 下 仅在 scripts/ 中留下真正的通用实用程序 如果路径发生了变化，请更新引用或命令 将分散的状态视为需要修复的内容，而不是可接受的起始模式 决策标准 优先选择一种结构，使得未来的读者很容易知道从哪里开始。 如果有疑问，首先创建一个项目文件夹，并将该工作的所有内容放在 projects// 下。