project-structure

项目结构

仅应用请求的工作所需的角色和文档。保留有效的项目约定；如需进行重大结构调整，应在实施前说明。语言和技术栈技能负责语言特定的命令和配置。

核心布局

根据生态系统为这些角色命名：

• 根目录：面向用户的 README.md、清单、一个规范锁文件、Agent 上下文、可选的贡献规则和治理文件。
• 源码：一个惯用的源码根目录，按领域或命名空间组织。
• 测试：单元测试与源码同置；端到端测试套件放在一个由项目管理的顶层位置；仅为已交付或易出现回归的层添加特定层级的测试。
• docs/：架构、快速入门、工具、代码风格和部署。
• 脚本：一次性自动化脚本放在 scripts/、bin/ 或 tools/ 中。
• 生成的输出：一个被忽略的构建／输出位置。
• 可选项：生成器模板、静态资源和已配置的 Agent 技能。

测试必须能捕获有意义的回归。端到端测试是系统级的主要防护网；单元测试覆盖公共模块行为，但不重复相同断言。

治理

采用此风格的项目会保留这些规范根文件：

• VISION.md：持久的产品和技术方向，包括明确不做的事项。
• DEFINITION_OF_READY.md：实施前的硬性门槛。
• DEFINITION_OF_DONE.md：将变更视为可发布前的硬性门槛。

在多领域仓库中，以最近的领域专属文件为准。治理、Agent、贡献者和项目文档之间应相互链接，而不是重复政策。工作流要求某个治理文件但该文件缺失时，应标明；不要擅自编造替代文件。

Agent 上下文

AGENTS.md 是规范文件。CLAUDE.md 是普通文件，其首行必须为 @AGENTS.md，之后只能包含真正针对 Claude 的补充内容。它适用于无法直接读取 AGENTS.md 的 Claude Code 会话；导入的 AGENTS.md 绝不会被重复加载。绝不要复制文件，也不要使用符号链接：在未启用 core.symlinks 的 Windows 上，Git 会将符号链接检出为一行文本文件，而 Claude Code 的 Edit 和 Write 工具也拒绝通过符号链接写入。请将符号链接或复制而来的 CLAUDE.md 替换为导入文件，并更新所有依赖该链接的内容。

根目录的 AGENTS.md 应保持精简：简要说明仓库，然后将上下文用于说明不明显的注意事项、准确命令、硬性约束和安全边界。不要重述文件树或仓库中显而易见的约定。

仅在规则不同时添加嵌套的 <area>/AGENTS.md；根文件应指向各领域文件。使用 CONTRIBUTING.md 说明权威的人为合并要求，并通过链接引用，而非重复说明。

如果已配置精选技能，.agents/skills/ 和 skills-lock.json 由技能工具生成，绝不能手动编辑。将 .claude/skills 符号链接到 .agents/skills。

情境参考

• 创建或重构 README、文档、治理文件、Agent 文件或多领域仓库时，请阅读 references/documentation.md。
• 安装钩子、脚本、变更日志生成、Markdown／链接／重复内容检查或架构偏移强制检查时，请阅读 references/tooling.md。

完成标准

• 仓库声明的验证门槛已通过。
• 本次工作修改的文档均为最新内容，且各有唯一的权威位置。
• 生成文件通过其所属工具修改。
• 未引入无关的结构迁移。