Qoder `.qoder` 目录完全指南

霸道流氓气质2026-06-19 18:02

Qoder .qoder 目录完全指南

一、什么是 .qoder 目录

.qoder 是 Qoder（原 CodiumAI） AI 编程工具的项目级配置目录，存放在项目根目录下。它的核心作用是为 AI 提供两类上下文信息：

  1. 你定义的规则（rules）--- 告诉 AI 该怎么做
  2. AI 自动生成的知识库（repowiki）--- AI 自己学到的项目知识

当你在 Qodo 中生成代码、提问或做代码审查时，这些文件会被自动加载，确保 AI 理解你的项目背景和规范要求。

二、目录结构

复制代码 
.qoder/
├── rules/                       ← 手动维护的编码规则
│   ├── product.md               ← 产品/业务背景
│   ├── structure.md             ← 项目结构与分层约定
│   └── tech.md                  ← 技术栈与工具链
│
└── repowiki/                    ← AI 自动生成的项目知识库
    └── {lang}/                  ← 语言分区（如 zh、en）
        ├── content/             ← 结构化文档内容
        │   ├── 快速开始.md
        │   ├── API文档/
        │   ├── 业务逻辑/
        │   ├── 数据模型/
        │   ├── 架构设计/
        │   ├── 核心模块/
        │   ├── 开发指南/
        │   └── 故障排查/
        └── meta/
            └── repowiki-metadata.json  ← 代码片段索引

三、rules/ 目录详解

作用

等同于 Kiro 的 .kiro/steering/、Cursor 的 .cursorrules、Copilot 的 .github/copilot-instructions.md，是你主动告诉 AI 的项目规则和背景。

文件分类

文件 职责 内容示例
product.md 业务背景与产品定位 产品是什么、服务于谁、核心业务域
structure.md 代码结构与架构约定 目录布局、包命名、分层模式、URL 规范
tech.md 技术栈与工具链 语言版本、框架、构建工具、CI/CD、常用命令

生效方式

Qodo 插件启动时自动扫描 .qoder/rules/ 目录下的所有 .md 文件，将内容注入到 AI 对话上下文中。无需手动引用。

注：

博客：

https://blog.csdn.net/badao_liumang_qizhi

四、repowiki/ 目录详解

作用

Qodo 的仓库知识库功能------自动扫描项目源码，生成结构化的项目文档。相当于 AI 给项目做了一次全面的"阅读理解"并输出笔记。

工作原理

  1. Qodo 分析项目中的启动类、配置文件、API 接口、Service 层、实体类等
  2. 按主题分类生成 Markdown 文档
  3. 文档中标注代码来源（文件路径 + 行号），方便追溯
  4. meta/repowiki-metadata.json 记录代码片段索引，用于增量更新

文档主题分类

目录 涵盖内容
快速开始 环境搭建、本地启动、基础验证
API 文档 接口定义、DTO 结构、调用方式
业务逻辑 核心业务流程和规则
数据模型 实体关系、枚举、核心表结构
架构设计 整体架构、集成模式、事务管理
核心模块 各模块的详细设计与实现
开发指南 编码规范、开发流程
故障排查 常见问题与解决方案

metadata.json 的作用

json 复制代码 
{
  "code_snippets": [
    {
      "id": "唯一ID",
      "path": "src/main/java/com/example/Application.java",
      "line_range": "1-29",
      "gmt_create": "2026-06-08T15:53:26",
      "gmt_modified": "2026-06-08T15:53:26"
    }
  ]
}

记录 AI 在生成文档时引用的代码片段坐标，用于：

  • 文档与代码的双向链接
  • 代码变更后增量更新文档
  • 避免重复分析已处理的代码

五、通用 Spring Boot 项目示例

示例 product.md

markdown 复制代码 
# Product Overview

This workspace contains a **SaaS multi-tenant order management platform** --- a suite of 
Java microservices for e-commerce order lifecycle management.

## Core Business Domains

- **Order**: Order creation, modification, cancellation, and lifecycle tracking
- **Inventory**: Real-time stock availability, reservation, and release
- **Payment**: Payment gateway integration, refund processing
- **Shipping**: Logistics provider integration, tracking, and delivery confirmation
- **Customer**: Customer profiles, addresses, and preferences

## Key Capabilities

- Multi-tenant data isolation via schema-per-tenant strategy
- Event-driven architecture with eventual consistency
- Real-time inventory synchronization across channels
- Distributed transaction management (Saga pattern)
- Integration with third-party logistics and payment providers

## Platform Context

- Target users: Mid-size e-commerce merchants
- Deployment: Kubernetes on AWS EKS
- Traffic: ~5000 orders/minute at peak

示例 structure.md

markdown 复制代码 
# Project Structure

## Workspace Layout

This is a multi-module Maven project with domain-driven package structure.

| Module | Description | Package |
|--------|-------------|---------|
| order-service | Order lifecycle management | `com.example.order` |
| inventory-service | Stock management | `com.example.inventory` |
| payment-service | Payment processing | `com.example.payment` |
| shipping-service | Logistics integration | `com.example.shipping` |
| common-lib | Shared utilities and DTOs | `com.example.common` |

## Service Internal Structure

src/main/java/com/example/{service}/ ├── Application.java ├── config/ # Spring configuration ├── domain/ │ ├── {aggregate}/ │ │ ├── controller/ # REST controllers │ │ ├── service/ # Business logic │ │ │ └── impl/ │ │ ├── repository/ # Data access (MyBatis Mapper) │ │ ├── entity/ # Database entities │ │ ├── dto/ # Data transfer objects │ │ │ ├── request/ # API request DTOs │ │ │ └── response/ # API response DTOs │ │ ├── enums/ # Enum types │ │ ├── event/ # Domain events │ │ └── exception/ # Domain exceptions │ └── shared/ # Cross-aggregate utilities ├── infrastructure/ │ ├── mq/ # Message queue producers/consumers │ ├── feign/ # Feign clients + fallback factories │ ├── cache/ # Cache configuration │ └── external/ # Third-party API clients └── common/ ├── result/ # Unified response wrapper ├── exception/ # Global exception handler └── util/ # Common utilities

复制代码 
## API URL Conventions

- Public APIs: `/api/v1/{resource}/{action}`
- Internal APIs: `/api/internal/{resource}/{action}`
- Admin APIs: `/api/admin/{resource}/{action}`

## Resources

src/main/resources/ ├── application.yml ├── application-{profile}.yml ├── bootstrap.yml ├── mapper/ # MyBatis XML mapper files ├── i18n/ # Internationalization └── db/migration/ # Flyway migration scripts

复制代码

示例 tech.md

markdown 复制代码 
# Tech Stack

## Language & Runtime

- **Java 17** (LTS)
- **Lombok** (`@Data`, `@Builder`, `@Slf4j`, `@RequiredArgsConstructor`)

## Frameworks

- **Spring Boot 3.2.x**
- **Spring Cloud 2023.x** with Alibaba Nacos for discovery and config
- **Spring Cloud OpenFeign** for inter-service HTTP calls
- **Spring Cloud Gateway** as API gateway

## Build System

- **Maven** with multi-module structure
- Parent POM manages dependency versions via BOM

## Data Layer

- **MySQL 8.0** as primary database
- **MyBatis-Plus** for ORM and SQL mapping
- **Flyway** for database migrations
- **Spring Data Redis** for caching and distributed locks
- **ShardingSphere** for read-write splitting

## Messaging

- **Apache Kafka** for event-driven communication
- **RocketMQ** for transactional messages

## API Documentation

- **SpringDoc OpenAPI 3** with Knife4j UI

## Testing

- **JUnit 5** (Jupiter)
- **Mockito** + **MockMvc**
- **Testcontainers** for integration tests

## Code Quality

- **Checkstyle** with Google style
- **SpotBugs** for static analysis
- **JaCoCo** for coverage (minimum 70%)

## CI/CD

- **GitHub Actions** with stages: build → test → sonar → deploy
- **Docker** + **Kubernetes** for containerized deployment
- **Helm** charts for environment configuration

## Common Commands

```bash
# Build all modules
mvn clean install -DskipTests

# Run a specific service
mvn spring-boot:run -pl order-service

# Run tests
mvn test

# Run checkstyle
mvn checkstyle:check

# Generate API docs
mvn springdoc-openapi:generate
---

六、与其他 AI 工具配置对照

维度 Qodo .qoder/ Kiro .kiro/ Copilot Cursor
规则文件 rules/*.md steering/*.md .github/copilot-instructions.md .cursorrules
知识库 repowiki/（自动生成） 无 无 无
运行时拦截 无 hooks/*.kiro.hook 无 无
文件引用 无 #[[file:]] 语法 无 @file 语法
生效方式 插件自动加载 自动/手动/条件匹配 自动 自动
多文件规则 ✅ 支持 ✅ 支持 ❌ 单文件 ❌ 单文件

七、最佳实践

1. rules/ 的编写原则

  • 简洁明确：每个文件聚焦一个主题，避免过长
  • 用表格和列表：AI 解析结构化内容比纯文本更准确
  • 提供正反例：告诉 AI "应该怎样"同时也说"不要怎样"
  • 保持更新：技术栈升级或架构变更后同步修改

2. repowiki/ 的维护策略

  • 定期触发重新生成，保持文档与代码同步
  • 生成的文档可以提交到 Git，供团队成员参考
  • 如果文档有误，修正代码后重新生成（不建议直接改文档）

3. 跨工具规则复用

rules/ 中的内容可以作为规则的"单一来源"，通过脚本同步到其他工具：

bash 复制代码 
# 将 .qoder/rules/ 的内容合并输出到其他工具配置
cat .qoder/rules/product.md .qoder/rules/structure.md .qoder/rules/tech.md \
  > .github/copilot-instructions.md

cp .github/copilot-instructions.md .cursorrules

八、总结

组件 本质 维护方式 作用
.qoder/rules/ 项目规则手册 开发者手动编写 约束 AI 的行为和输出
.qoder/repowiki/ 项目知识图谱 Qodo 自动生成 帮助 AI 理解项目全貌

两者的关系：rules 是"法律"，repowiki 是"百科全书"。法律约束行为，百科提供背景知识。AI 结合两者，才能生成真正符合项目实际的代码。

热门推荐
012026年6月AI行业全景：从百模大战到Agent元年，这30天发生了什么？022026年6月AI大模型全景报告：GPT-5.6、Claude Opus 4.8、Gemini 3.5，中美AI三足鼎立谁主沉浮？032026 年 AI 编程工具终极横评：Cursor vs Claude Code vs Copilot vs Windsurf04【AI】2026 年具身智能模型和世界模型总结05GitHub 镜像站点06AI科技热点日报 | 2026年6月1日07AI一周事件 · 2026-06-03 至 2026-06-09082026 AI 编程工具终极实战指南：Cursor vs Claude Code vs Copilot，开发者该怎么选？09Claude Code、Codex、Cursor三分天下：2026年AI编程Agent生态全景剖析10上线仅72小时被强制下架：Claude Fable 5 的短命