goose 的 .goosehints 上下文工程从全局到嵌套目录的项目级提示词机制【免费下载链接】goosean open source, extensible AI agent that goes beyond code suggestions - install, execute, edit, and test with any LLM项目地址: https://gitcode.com/GitHub_Trending/goose3/goose.goosehints是 goose 用来向 Agent 注入项目上下文的纯文本提示文件它让 goose 在每次会话中“记住”你的编码规范、构建流程和验证习惯。本文基于 goose 仓库的官方指南using-goosehints.md展开并结合 hints 模块源码 与测试用例讲清它的文件组织方式、引用展开机制、嵌套目录加载逻辑以及CONTEXT_FILE_NAMES自定义配置帮助你在单仓与 monorepo 中高效组织 Agent 上下文。什么是 .goosehints什么时候该加一个.goosehints是一个文本文件用于提供关于你项目的额外上下文从而改善与 goose 的沟通。使用.goosehints可以确保 goose 更好地理解你的需求并更有效地执行任务。适合引入.goosehints的典型时机你发现自己在反复重复同样的提示词或多次给出同一类指令你有大量上下文规范、流程、约束更适合放在文件里而不是每次手敲。:::提示使用 hints 文件前需要启用Developer扩展参见 使用扩展。:::从源码结构看hints 的整条链路集中在 crates/goose/src/hints/load_hints.rs负责文件发现与层级加载import_files.rs负责引用的安全展开加载结果最终由 prompt_manager.rs 作为系统提示的附加指令注入。创建 Hints 文件全局与本地两种作用域goose 支持两类提示文件全局提示文件Global hints file对 goose 的所有会话生效与目录无关存放在~/.config/goose/.goosehints。本地提示文件Local hints files只在特定目录或其目录层级下工作时生效。两者可以同时使用。当两者都存在时goose 会同时考虑你的全局偏好和项目特定要求如果本地 hints 文件中的指令与全局偏好冲突goose 会优先采用本地 hints。goose Desktop 界面方式全局 hints 文件在~/.config/goose中创建.goosehints文件。本地 hints 文件点击应用底部的工作目录路径打开你要创建文件的目录点击左上角汉堡菜单按钮打开侧边栏在侧边栏点击Settings点击Chat向下滚动到Project Hints (.goosehints)区域并点击Configure在文本域中输入你的本地 hints点击Save重启会话让 goose 读取更新后的.goosehints。如果目标目录中已存在.goosehints文件可以直接编辑已有内容。手动方式全局在~/.config/goose下创建.goosehints。本地在项目根目录和/或层级中的任意目录下创建.goosehints。在源码中全局文件通过Paths::in_config_dir(name)定位即~/.config/goose/下的指定文件名本地文件则按工作目录向上查找详见后文 加载机制。编写 Hints自然语言 文件引用.goosehints支持自然语言。请使用清晰、具体的指令和直接的语言让 goose 容易理解和遵循写入项目与工作流偏好等上下文并把最重要的规范放在前面。goose 在会话开始时加载 hints。随着它访问嵌套目录中的文件它也会加载这些目录的 hint 文件。goose 会把 hints 加入每次请求的系统提示中。由于.goosehints内容会消耗 token保持精简有助于降低成本并提升性能。全局.goosehints示例Always use TypeScript for new Next.js projects. coding-standards.md # Contains our coding standards docs/contributing.md # Contains our pull request process Follow the [Google Style Guide](https://google.github.io/styleguide/pyguide.html) for Python code. Run unit tests before committing any changes. Prefer functional programming patterns where applicable.本地.goosehints示例This is a simple example JavaScript web application that uses the Express.js framework. View [Express documentation](https://expressjs.com/) for extended guidance. Go through the README.md for information on how to build and test it as needed. Make sure to confirm all changes with me before applying. Run tests with npm run test ideally after each change.这两个示例展示了引用其他文件的两种写法语法自动把文件内容包含进 goose 的即时上下文普通引用只是告诉 goose 需要时再去查看该文件适合可选的或非常大的文件。引用的底层展开机制引用的实际展开实现在 import_files.rs几个关键行为可以从源码和测试确认展开格式被引用的文件内容会被包裹为--- Content from 引用路径 ---...--- End of 引用路径 ---插入原位置见 test_hints_with_basic_imports 中的断言支持嵌套引用被引用的文件内部还可以继续用引用其他文件level1.md→level2.md的用例见 test_nested_reference但递归深度上限为MAX_DEPTH 3预算控制单次展开最多64次引用操作MAX_REFERENCE_OPERATIONS、总输出上限1 MBMAX_EXPANDED_OUTPUT_BYTES且单文件内容超过 128 KB 时不再做引用解析防 ReDoS。这些常量定义在 import_files.rs#L14-L17安全边界引用只允许相对路径禁止绝对路径展开边界是git 仓库根目录无.git时退化为当前目录指向边界之外、或指向.git元数据目录包括 worktree 的commondir链路和指向外部的符号链接的引用会被拒绝并保留原文。测试test_hints_with_git_import_boundary、test_worktree_git_directories_are_not_imported等覆盖了这些场景.gitignore过滤被引用文件如果命中.gitignore规则则不会被导入例如*.env文件避免把敏感内容带入提示词。嵌套 .goosehintsmonorepo 的层级化上下文goose 在 git 仓库中支持层级化的本地 hints。会话开始时goose 会从你的工作目录一路向上到仓库根目录加载各层已配置的上下文文件当 goose 在会话中读取或修改嵌套子目录里的文件时还会自动发现并加载这些目录中的额外 hint 文件。这在 monorepo 或大型项目中特别有用——代码库不同部分往往有不同的约定。默认情况下goose 在每一级都会查找AGENTS.md和.goosehints两个文件名。如果你使用了自定义上下文文件goose 会对这些自定义文件名应用同样的嵌套加载行为。最佳实践是每一级的.goosehints只写与该作用域相关的 hints根级别全项目通用的规范、构建流程、总体指南模块/功能级别该代码区域的具体要求目录级别非常具体的上下文如本地测试流程、组件模式。示例项目结构my-project/ ├── .git/ ├── .goosehints # Project-wide hints ├── frontend/ │ ├── .goosehints # Frontend-specific hints │ └── components/ │ ├── .goosehints # Component-specific hints │ └── Button.tsx └── backend/ ├── .goosehints # Backend-specific hints └── api/ └── routes.py如果在my-project/启动 goose根级 hints 会立即加载之后当 goose 访问frontend/components/下的文件时会加载该路径的嵌套 hints并按以下顺序组合my-project/.goosehints项目根This is a React TypeScript project using Vite. README.md # Project overview and setup instructions docs/development-setup.md # Development environment configuration Always run tests before committing: npm test Use conventional commits for all changes.frontend/.goosehintsThis frontend uses React 18 with TypeScript and Tailwind CSS. package.json # Dependencies and scripts docs/frontend-architecture.md # Frontend structure and patterns ## Development Standards - Use functional components with hooks (no class components) - Implement proper TypeScript interfaces for all props - Follow the component structure: /components/ComponentName/index.tsx - Use Tailwind classes instead of custom CSS when possible ## Testing Requirements - Write unit tests for all components using React Testing Library - Test files should be co-located: ComponentName.test.tsx - Run npm run test:frontend before committing changes ## State Management - Use React Query for server state - Use Zustand for client state management - Avoid prop drilling - lift state appropriately Always confirm UI changes with design team before implementation.frontend/components/.goosehints当前目录Components in this directory use our design system. docs/component-api.md # Component interface standards and examples All components must: - Export a default component - Include TypeScript props interface - Have corresponding .test.tsx file - Follow naming convention: PascalCase注意某个目录的嵌套 hints 加载后会在整个会话期间保持生效。如果你修改了 hint 文件并希望 goose 可靠地读取新内容请重启会话。嵌套加载的源码验证两个测试用例清晰界定了“向上查找”的前提是 git 仓库test_nested_goosehints_with_git_root在存在.git的仓库中从subdir/current_dir启动时会按“根 → 子目录 → 当前目录”顺序拼接三层 hintsRoot hints content\nSubdir hints content\ncurrent_dir hints contenttest_nested_goosehints_without_git_root没有.git时只加载当前目录的 hints不会向上越界查找。“会话中访问子目录后自动补载 hints”的逻辑由SubdirectoryHintTracker实现load_hints.rs#L26-L103它监视工具调用的path参数与command命令中出现的文件路径解析出其所在目录然后在下一轮提示构建时把新目录下所有配置的上下文文件含展开结果以subdir_hints:目录为键注入系统提示。相关行为均有测试保障同一目录去重tracker_deduplicates_directories、拒绝../越出工作目录的路径tracker_rejects_parent_traversal_outside_working_directory、拒绝指向外部目录的符号链接tracker_rejects_directory_symlink_outside_working_directory、目录尚不存在时延迟重试tracker_retries_directory_after_parent_is_created。在 prompt_manager.rs 中可以看到 hints 与系统提示的最终合并方式with_hints()先调用get_context_filenames()、build_gitignore(working_dir)和load_hint_files()再把结果以hints键写入 system prompt extrasbuild()时统一追加在# Additional Instructions:段落之后。全局与本地内容在注入时还会分别带上### Global Hints与### Project Hints的标题load_hints.rs#L294-L308这也就是本地 hints 能覆盖全局偏好的实现基础。常见使用场景以下是社区使用 hints 提供额外上下文的一些方式决策方式Decision-Making说明 goose 应自主做出更改还是先与你确认验证流程Validation Routines提供 goose 应执行的测试用例或验证方法确保更改符合项目规范反馈循环Feedback Loop包含让 goose 获取反馈并迭代改进建议的步骤指向更详细的文档指明README.md、docs/setup-guide.md等 goose 应查阅的重要文件用 -mention 组织内容对经常需要的文档使用filename.md或relative/path/testing.md自动把文件内容纳入当前上下文而不仅仅是引用它确保 goose 能即时访问关键信息。核心文档如 API schema、编码规范建议用-mention 提供即时上下文可选或非常大的文件则用普通引用不带。和提示词一样这并不是一个穷尽清单。你可以在.goosehints中包含任何你需要的上下文量。最佳实践保持文件更新随着项目规范或优先级变化定期更新.goosehints保持简洁内容直截了当确保 goose 能快速解析并执行从小处开始先建一组清晰具体的小 hints再按需逐步扩展便于观察 goose 如何理解和应用指令引用其他文件指向/docs/style.md、/scripts/validation.js等文件减少重复、保持指令轻量。自定义上下文文件CONTEXT_FILE_NAMESgoose 默认按AGENTS.md然后.goosehints的顺序查找上下文文件但你可以通过CONTEXT_FILE_NAMES环境变量配置不同的文件名或多个上下文文件。典型用途工具兼容沿用其他 AI 工具的约定如CLAUDE.md组织方式把常用规则拆分为多个自动加载的文件项目约定沿用项目既有工具链的上下文文件如.cursorrules。工作流程goose 在全局~/.config/goose/和本地项目位置分别查找每个配置的文件名会话开始时从工作目录层级加载匹配的文件会话过程中访问嵌套子目录时可加载额外的匹配文件所有找到的文件都会被加载并组合进上下文。配置把CONTEXT_FILE_NAMES环境变量设为一个 JSON 文件名数组。默认值为[AGENTS.md, .goosehints]源码中由 get_context_filenames() 从全局配置读取读不到时回退到AGENTS.md与.goosehints这两个常量文件名。# Single custom file export CONTEXT_FILE_NAMES[AGENTS.md] # Project toolchain files export CONTEXT_FILE_NAMES[.cursorrules, AGENTS.md] # Multiple files export CONTEXT_FILE_NAMES[CLAUDE.md, .goosehints, project_rules.txt]多文件名同时加载的行为由 test_goosehints_multiple_filenames 验证CLAUDE.md与.goosehints存在时两者内容都会进入提示test_goosehints_configurable_filename则验证只配置CLAUDE.md时不会再去加载默认的.goosehints。此外源码还显示当文件名列表包含AGENTS.md时全局查找范围会额外覆盖用户主目录下的.agents/AGENTS.md见 test_global_agents_md_in_agents_home 用例。goose 仓库本身就是这种多文件约定的实践者——根目录同时存在 AGENTS.md、CLAUDE.md 与 .goosehints。小结.goosehints分为全局~/.config/goose/.goosehints与本地项目内各级目录两层冲突时本地优先会话启动时加载工作目录到 git 仓库根的各级 hints会话中首次访问子目录时会按需补载该目录 hints且整会话保持生效——修改文件后建议重启会话文件引用会把内容含嵌套引用就地展开进提示受深度 3 层、64 次操作、1 MB 输出与 gitignore/边界规则约束适合核心文档大文件或可选文件用普通引用通过CONTEXT_FILE_NAMES可把CLAUDE.md、.cursorrules等既有约定文件纳入同一套全局/嵌套加载机制实现团队工具链的平滑迁移。【免费下载链接】goosean open source, extensible AI agent that goes beyond code suggestions - install, execute, edit, and test with any LLM项目地址: https://gitcode.com/GitHub_Trending/goose3/goose创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
