IntelliJ Community 仓库 AI 协作开发指南从 guide 模板渲染到 Bazel 构建与测试规范【免费下载链接】intellij-communityIntelliJ IDEA IntelliJ Platform项目地址: https://gitcode.com/GitHub_Trending/in/intellij-community本指南以 IntelliJ IDEA Community Edition 开源仓库intellij-community中的 AI 协作开发基准文档 .ai/guide.md 为骨架完整讲解仓库为 AI 编码 Agent 制定的项目不变量、写作规范、强制测试/构建规则与工具链约束并结合渲染器源码 .ai/render-guides.mjs 与配套文档深入其生成机制。读完本文你将掌握该仓库中 Agent 应遵循的完整工作流如何登记 JPS 模块、如何跑通 Bazel 编译与格式化校验、如何选择搜索与语义工具以及AGENTS.md、CLAUDE.md等引导文件的生成原理。一、guide.md 是什么AI 引导文档的模板之源.ai/guide.md不是一份给人读的普通文档而是整个仓库 AI 协作引导体系的模板源文件。仓库用渲染器 .ai/render-guides.mjs 把该模板渲染成多种 Agent 工作环境可用的引导文件包括AGENTS.mdCodex / 通用 AgentCLAUDE.mdClaude仅 ULTIMATE 版本输出.junie/AGENTS.mdJuniecommunity/AGENTS.mdULTIMATE 工作区内的社区版引导OpenCode 配置与 skill 存根、工具权限规则等这一点在 .ai/README.md 中有明确说明模板目录community/.ai存放模板与文档源渲染命令为bazel run //.ai:render-guides渲染目标通过 Bazel 固定的 bun 运行时执行render-guides.mjs而不是用机器上的node。模板源顶部也留有生成标记!-- TEMPLATE:COMMENT -- To regenerate, run bazel run //.ai:render-guides. !-- /TEMPLATE:COMMENT --模板指令同一份源多版本输出guide.md 内部通过三类模板指令实现一份模板、按目标环境裁剪IF_EDITION按版本COMMUNITY/ULTIMATE裁切内容。例如 JPS 模块登记后的重建命令在两种版本下分别是./build/jpsModelToBazelCommunityOnly.cmd与./build/jpsModelToBazel.cmd。IF_TOOL按工具如CODEX裁切内容例如 Codex 环境下 MCP 工具前缀mcp__ijproxy__name的说明。TEMPLATE:COMMENT仅供模板编写者阅读的内部注释渲染时整块移除。此外还有两类占位符{{TOOLS_DIR}}按版本解析为搜索包装器所在目录ULTIMATE 为./community/toolsCOMMUNITY 为./tools{{PARTIAL:name}}注入局部片段例如module-specific、code-ownership、knowledge-mcps等。若渲染结束后仍有未解析占位符渲染器会快速失败fail fast避免产出残缺文档。版本解析顺序在渲染器中定义为环境变量AI_GUIDE_EDITION→RENDER_EDITION→.ultimate.root.marker文件是否存在存在即 ULTIMATE否则 COMMUNITY。也可强制指定AI_GUIDE_EDITIONCOMMUNITY bazel run //.ai:render-guides AI_GUIDE_EDITIONULTIMATE bazel run //.ai:render-guides二、项目不变量Agent 必须始终遵守的底层约束guide.md 开篇即强调Project Invariants项目不变量这是仓库自洽性的根基模块目录可自持指引模块或插件目录可以拥有自己的AGENTS或CLAUDE指令文件若存在则优先遵循。*.iml是唯一事实来源*.iml文件生成对应的BUILD.bazel文件任何构建模型改动都以.iml为准。JPS 模块登记流程新增或编辑 JPS 模块.iml后必须先用以下命令登记再重建 Bazel 模型社区版bun build/jps-module.mjs register path-to-iml --fix-iml-eof ./build/jpsModelToBazelCommunityOnly.cmd并且绝不手改.idea/modules.xml——命令会保持modules.xml的规范顺序。ULTIMATE 版本对应执行./build/jpsModelToBazel.cmd。用户可见字符串必须进*.properties以便支持本地化不允许把界面文案硬编码在代码里。这些不变量决定了仓库内任何模块改动的基本流程也解释了为什么仓库根目录存在 build/jpsModelToBazelCommunityOnly.cmd 这类重建脚本。三、写作规范全仓库统一的 ASD-STE100 简化技术英语guide.md 要求所有用户可见产物——注释、KDoc、提交信息、文档、规格说明、给用户的报告——一律使用ASD-STE100Simplified Technical English简化技术英语书写保持简短。核心要求是主动语态、简单时态、一句一个主题、肯定式表达、名词簇不超过三个词。文档特别提炼了五条最能挽回损失的规则规则要求示例说明句子长度单句不超过 25 词超长句必须拆分插入语插入语独立成句禁止夹在两个破折号之间保留冠词写 the session不写 session保持冠词完整术语唯一一个概念只用一个术语禁止为既有术语引入同义词诚实完整说明省略了什么及原因不要用填充文字假装报告完整同时每种文本有且只有一个归宿变更的理由与证据进提交信息commit message不进代码注释对声明的解释写在该声明旁的 KDoc 里而不是放进README.md。这一原则与 .ai/spec/SPEC_GUIDE.md 中规格只描述可观察行为实现机制归 KDoc、决策理由归 ADR、未来策略归模块 AGENTS.md的分层思想一脉相承。正式写或评审 Kotlin / Java 之前需先阅读代码风格技能文档 .agents/skills/code-style/SKILL.md。四、工作区隔离禁止擅自建 worktree 与克隆仓库体量过大不允许 Agent 为隔离工作区而临时创建 Git worktree 或额外克隆。guide.md 明确要求在采取任何工作区隔离动作之前必须先阅读 .ai/workspace-isolation.md。该配套文档进一步规定需要隔离工作区时使用treehouse技能注即.agents/skills/treehouse/SKILL.md且不得绕过其封装直接调用原始 Treehouse 生命周期命令如treehouse enter、init、update、prune、destroy、--force。不得擅自执行git worktree add、克隆仓库或实现其他自定义隔离机制。若 Treehouse 命令失败不得擅自回退到 worktree、克隆或其他工作区管理器应在当前 checkout 中安全继续或请用户提供隔离工作区。显式请求例外若用户明确要求为当前任务创建 Git worktree则只创建一个、且严格限定于该任务不要求用户手动创建。五、强制规则改代码后与写完代码后必须做的事改代码之后After Code Changes运行受影响的测试命令格式为./tests.cmd --module module --test FQN or wildcard对于*.test.mjs文件则使用node --test file。注意测试必须用完整限定名FQN简单类名不会匹配任何测试必须始终指明测试模块名。tests.cmd自身通过 Bazel 编译因此无需单独执行bazel build模块规则可覆盖测试运行器插件没有测试时可跳过。详见测试技能文档 .agents/skills/testing/SKILL.md。仅验证编译只想确认编译通过时运行bazel build target覆盖受影响模块。若只改动了.js、.mjs、.md、.txt、.json文件则可跳过编译验证。Bazel / Starlark 源改动后的格式化改动BUILD、BUILD.bazel、MODULE.bazel、WORKSPACE、WORKSPACE.bazel或*.bzl后先运行bazel run //:format.check若报告差异则运行bazel run //:format检查改动后再跑一次 check。模型文件改动后的重建改动*.iml、BUILD.bazel或.idea/文件后社区版运行./build/jpsModelToBazelCommunityOnly.cmd重新生成构建模型。写完代码之后After Writing Code当 ijproxy 或 JetBrains MCP 可用时用lint_files检查文件警告修复属于自己改动引入的每一条警告无关的既有警告可以忽略。六、仓库级规则.iml文件的规范形态仓库要求 IDE 序列化的.iml文件保持规范形态canonical form禁止以下任何操作添加注释自动格式化规范化结构或空白在文件末尾添加换行trailing newline删除空标签重排元素或属性顺序也就是说.iml是机器与 IDE 共同维护的产物Agent 不应顺手美化它否则会造成与 IDE 序列化结果的持续漂移。七、工具链规则搜索、语义工具与命令边界搜索与导航优先 ijproxyguide.md 明确禁止使用code-search技能改由以下工具替代完整菜谱与 Windows 规则见 .ai/tools.md场景工具找类、方法或字段search_symbol按 glob 找文件search_file找字符串、注释等非符号内容search_text/search_regex在 Codex 环境下这些工具以mcp__ijproxy__name形式暴露使用 shell 或非 ijproxy 回退之前先检查延迟工具目录ALL_TOOLS。IDE 支撑的语义工具通过 ijproxy 或 JetBrains MCP 可获得lint_files、get_symbol_info、rename、reformat_file、线程与锁检查以及项目、VCS 和运行配置类工具。原则是优先做真正的重构real refactoring而不是手工搜索替换。工具使用硬性规则内容/符号搜索和语义操作优先 ijproxy回退顺序为 JetBrains MCP →fd.cmd文件与rg.cmd文本/正则。这两个包装器默认跳过点目录如.agents/必须传-H--hidden才能搜到 Agent 资产。禁止用 shell 做文件搜索仓库内外皆然Glob、Grep工具被拒绝grep与find命令在所有管道位置都被禁止。优先使用权限白名单已知的拼写新增条目应写入{{COMMUNITY_DIR}}.ai/tool-permissions.json即 .ai/tool-permissions.json绝不手改 harness 的白名单。Shell 仅在 guide 明确允许的场合使用git、构建与测试。工作副本之外shell 访问是任务范围的——只读本仓库工具产生的产物或用户/技能明确指定的内容不得探查机器。任务看起来属于某个技能覆盖范围时先读技能索引确认每个名称的用途再决定是否即兴操作技能索引为 .agents/skills/INDEX.md。个人偏好Agent 还需要读取个人偏好文件./.ai/local.md即 .ai/local.md该文件属于按开发者维护的内容由渲染器允许其不存在见渲染器中的perDeveloperReferencePaths定义。八、配套机制工具权限渲染与技能存根生成guide.md 所指的工具权限规则并非手写散落而是由 .ai/tool-permissions.json 统一维护的单一来源经渲染器写入各 harness 的声明式配置.claude/settings.json渲染器替换permissions.allow中所有Bash(...)条目及整个permissions.deny其余字段保持手写。.codex/rules/default.rules完全由渲染器生成。条目是argv 前缀而非命令字符串两个 harness 都按字面文本匹配规则因此./x条目会同时输出带./与不带./两种拼写见toRuleSpellings。渲染器还提供校验逻辑不允许空条目、不允许残留占位符若allow为空数组则直接报错。技能方面渲染器以两类来源生成存根社区来源技能community/.agents/skills/*/SKILL.md与仅 ULTIMATE 的手写技能.agents/skills/*/SKILL.md。生成产物带有标记!-- Generated by community/.ai/render-guides.mjs; edit ... --无该标记的文件视为手写 ULTIMATE 源。技能描述还有严格的字节预算单条description必须是非空单行 YAML 值、不超过 160 UTF-8 字节某版本全部描述合计不超过 6 KiB。渲染失败时应缩短被报告的规范描述并重跑渲染器不要直接编辑生成的存根。九、验证与自检渲染器自带测试渲染管线不是黑盒仓库为它提供了测试.ai/render-guides.test.mjs。本地运行node --test community/.ai/render-guides.test.mjs测试覆盖链接重写、版本/工具块裁切、部分注入、占位符解析、权限文件生成等核心函数如rewriteMarkdownLinks、applyEditionBlocks、loadToolPermissions、buildCodexRules。这一机制保证了模板改动 → 重新渲染 → 输出校验闭环的可靠性。十、常见故障排查.ai/README.md 给出了渲染过程中的典型问题与处理方向现象处理Unknown partial: ...检查部分文件名与{{PARTIAL:name}}拼写是否一致输出中意外缺失内容检查IF_TOOL/IF_EDITION守卫与所选版本生成文件中相对链接损坏源链接可能被移动重新渲染并验证重写目标残留旧技能目录若无生成标记清理逻辑会刻意保留它总结Agent 在本仓库工作的完整行动清单以 .ai/guide.md 为基准在 intellij-community 仓库中工作的 AI Agent 应遵循的闭环流程可概括为读指引若模块目录存在自己的AGENTS/CLAUDE指令则优先遵循写代码前读代码风格技能隔离工作区前读 .ai/workspace-isolation.md。写代码按 ASD-STE100 书写所有用户可见文本用户可见字符串放入*.properties。改模型编辑.iml后运行bun build/jps-module.mjs register path-to-iml --fix-iml-eof与./build/jpsModelToBazelCommunityOnly.cmd保持.iml规范形态绝不手改.idea/modules.xml。改构建文件Bazel / Starlark 改动后运行bazel run //:format.check必要时bazel run //:format。验证用./tests.cmd --module module --test FQN或node --test file运行受影响测试或bazel build target验证编译写完代码用lint_files清理自己引入的警告。搜代码优先 ijproxy 的search_symbol/search_file/search_text禁止用 shell 的grep/find做文件搜索。这套规范的本质是把构建模型以.iml为准、文本按 STE 写作、搜索走 IDE 支撑工具、测试必须指明模块与 FQN这些硬约束固化到 Agent 的工作流中让 AI 协作与 JetBrains 庞大的构建体系、本地化体系和平共处保证每一次改动都可验证、可复现。【免费下载链接】intellij-communityIntelliJ IDEA IntelliJ Platform项目地址: https://gitcode.com/GitHub_Trending/in/intellij-community创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考