Menu
自动检测和改善代码库的文件组织结构，确保代码具有清晰的模块化和分层架构。使用模块化分割（按功能领域）和分层抽象（按职责分层）的双重策略，在每次代码修改后自动运行检测，或在目录文件数超过阈值时触发。
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
| name | file-organization-governance |
| description | 自动检测和改善代码库的文件组织结构，确保代码具有清晰的模块化和分层架构。使用模块化分割（按功能领域）和分层抽象（按职责分层）的双重策略，在每次代码修改后自动运行检测，或在目录文件数超过阈值时触发。 |
使用此技能自动检测和改善代码库的文件组织结构，确保代码具有清晰的模块化和分层架构。该技能采用双重组织策略：按功能领域模块化分割和按职责分层抽象。
这里要特别明确：
“目录结构规范”不是只指这一份 skill 文本。
对本项目而言，目录结构规范系统至少包含以下几部分：
高层结构模型
collapsible-feature-root-architectureL1、L2、L3、还是其他明确协议；当前目录是否应保持 single feature root；何时允许 features/、shared/、platforms/文件角色落位规则
role-first-file-organization文件与目录命名规则
file-naming-conventionkebab-case 等命名层约束目录治理执行入口
file-organization-governance（本 skill）可执行治理脚本
scripts/governance/*scripts/governance/module-structure/*scripts/governance/checks/structure/lint-new-code-flat-directories.mjsscripts/governance/checks/structure/lint-new-code-file-role-boundaries.mjsscripts/governance/checks/structure/lint-new-code-frozen-directories.mjsscripts/governance/checks/naming/lint-new-code-directory-names.mjs目录结构协议 / contract 数据
module-structure.config.json 与 scripts/governance/module-structure/module-structure-contracts.mjs目录结构协议是固定白名单，不是可自由扩展的命名空间。当前只能从脚本测试中批准的协议名单里选择；白名单必须自上而下对齐高层结构规范。若高层规范已定义某个结构等级但脚本未实现，应优先视为脚本漏实现并补齐，而不是说该结构不受支持。任何新增高层未定义的新协议都必须先得到用户明确同意，再同步修改脚本白名单、协议定义、高层结构说明和相关 contract。禁止为了绕开现有结构冲突而新增开放型、冻结型、显式白名单型或换名过渡协议。
Protocol flat role 目录允许使用 __tests__/ 与 tests/ 作为测试专用子容器；新增测试默认优先放入 __tests__/，tests/ 主要保留给既有历史测试和迁移过渡；生产实现仍应作为直接文件回到对应的 feature、role 或 shared 边界。
这里还要明确一条对应原则：
高层目录规范、脚本协议、workspace contract 引用必须一一对应。
module-structure-contracts.mjs 里新增或放宽一个 protocol，却没有同步把它对应到高层结构规范module-structure.config.json 引用一个协议名，而该协议在高层规范里没有 owner、适用边界和约束说明collapsible-feature-root-architecturerole-first-file-organizationscripts/governance/module-structure/*module-structure.config.json这里再加一条仓库级硬规则：
每个 workspace 根默认都必须显式声明 module-structure.config.json。
apps/*、packages/*、packages/extensions/*、packages/ncp-packages/*、workers/* 等实际 workspace 根因此，当用户说“调整目录结构规范”时，默认不能只改这一份 skill，而要检查：
scripts/governance/* 是否已有对应自动化检查module-structure.config.json 的检查是否也要同步更新如果最终只改了其中一层，必须明确说明为什么其他层不适用。
这里的 scope root 包括但不限于：
shared/lib/<module>/ 这类显式模块根默认原则统一为：
root 保边界，角色文件回角色目录。
contributions/ 是 kernel / runtime 级 package 可使用的旁路能力结构角色，不属于普通 app/frontend 的默认骨架。若某个 package contract 开放 contributions/，治理脚本应按 contributions/<name>/index.ts 唯一入口与内部角色子目录来约束；contribution 内部可以继续使用 contributions/<child>/index.ts 隔离局部分支能力，但嵌套 contribution 也必须遵循唯一入口和角色子目录规则，避免 contribution 内部变成新的平铺杂物目录。
对于前端展示层项目，再额外加一条强约束：
presenters/、managers/、stores/ 必须真实存在，不是可选建议。
L1 单根作用域，它们默认应出现在该作用域根下L3 / 多 feature 作用域，它们可以落在 app/、feature root 或平台作用域内，但不能整体缺席service 或 provider 文件名去“代替” presenter / manager / store 这三个 owner在以下情况触发此技能：
scripts/governance/* 与相关测试/contract 是否也要同步更新按功能领域将代码分割到不同的模块。以下是一些常见示例，可根据实际项目需求调整：
注意：以上仅为示例，实际项目应根据具体业务领域和功能进行模块划分。
在大型模块内部按职责分层。以下是一些常见示例，可根据实际项目需求调整：
注意：以上仅为示例，实际项目应根据具体架构模式和职责进行分层。
平铺职责目录硬约束：
hooks/ 与 services/、utils/、stores/ 一样，应被视为平铺职责目录；hooks/ 下禁止再出现子目录，只允许直接 hook 文件。lib/ 应被视为模块容器目录；lib/ 下只能出现模块子目录，不能直接放文件。共享能力应先落到 lib/<module>/，再由该模块目录的 index.ts / index.tsx 暴露公共出口。运行检测脚本分析目录结构：
node .agents/skills/file-organization-governance/scripts/enhanced-check-organization.js [目录路径]
根据输出建议确定重构方案
如需自动重构，使用重构脚本
hooks/，禁止用再套一层子目录来“分类”lib/，优先创建模块目录而不是直接堆文件当请求涉及“修改目录结构规范”而不是单次目录整理时，额外执行：
scripts/governance/* 是否已有对应检查在执行这条规则module-structure.config.json / protocol contract 是否也应同步调整Use when implementing, refactoring, or designing source-level contracts in this repository, especially if a task touches frontend/backend i18n or user-facing copy, frontend base/display components, tool schemas, API/protocol parameters, shared contracts, compatibility paths, fallback-heavy logic, duplicate branches, weak abstractions, unclear file placement, ad-hoc helpers, or patch-style fixes that would turn into garbage code.
Create or update complete NextClaw lightweight apps, deciding whether the user needs a Panel App, a Service App, or a combined Panel + Service App. Use for NextClaw applets, small tools, dashboards, local file tools, AI-assisted UI tools, apps that may combine right-side UI with backend actions, or questions about what NextClaw/Panel apps can do and which app APIs/capabilities they can use.
当用户要求提交、收尾、统一 NPM 发布、GitHub release、changelog、release notes、版本更新说明、产品更新笔记、变更汇总，或担心并行会话导致发布内容靠记忆整理时使用。适用于需要进入用户可见发布说明的 NextClaw workspace 包变更、Changesets 聚合、AI 撰写版本更新笔记、可拉取结构化 release notes JSON，以及 update manifest releaseNotesUrl 闭环。
Use when building, verifying, or releasing NextClaw desktop installers, DMGs, update bundles, update manifests, or one-command desktop beta/stable release automation. Enforces the packaged update public key contract, the required verification commands, and the rule that raw electron-builder output is not enough.
当用户要求“发布 beta”“统一 beta 发版”“发一个新的 NPM beta 版本”“一键 beta release”或希望直接复用 NextClaw 的 beta 发布闭环时使用。适用于 nextclaw 及其相关 workspace 包的 beta 发布，也适用于需要同时闭合 npm registry 与 NPM runtime update channel 的场景。
Use when publishing NextClaw NPM packages or NPM runtime update channels, including beta/stable dist-tags, nextclaw@beta validation, runtime bundle manifests, packaged update public keys, and npm registry closure checks.