Qoder平台提供五种项目结构：一、DDD平级Domains分层；二、Harness工程化目录模式；三、MCP扩展优先插件化结构；四、Quest任务导向型结构；五、Domains+Harness+MCP混合式分层，分别解决业务语义、AI可验证性、外部系统集成、任务生命周期及超大型工程协同问题。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您正在构建一个使用Qoder平台的大型工程，但项目结构松散、模块边界模糊、新成员难以快速定位功能或复用组件，则很可能是目录组织缺乏统一规范与工程约束。以下是针对Qoder生态设计的多种项目结构组织方法：
一、基于领域驱动（DDD）的平级Domains分层
该方式强调业务语义完整性，将每个核心业务域（如user、payment、notification）作为独立可演进单元，所有相关代码（模型、服务、接口、测试）物理聚拢，避免跨目录跳转，契合Qoder对“项目感知能力”的深度依赖要求。
1、在项目根目录下创建domains/子目录，不使用app/或src/等通用前缀。
2、为每个业务域新建子目录，例如domains/user/、domains/payment/。
3、在domains/user/内放置UserModel.py、UserRegistrationService.py、UserAPI.py、test_user_registration.py等全部关联文件。
4、在Qoder CLI中执行qoder init --structure domain-driven，自动注入PSR-4兼容的命名空间映射规则及测试路径镜像配置。
5、在domains/__init__.py中声明__all__ = ["user", "payment"]，确保Qoder Skills脚本能通过import domains.user自动解析上下文。
二、Qoder Harness工程化目录模式
该模式以AI可验证性为核心，将架构约束、lint规则、测试契约显式编码进目录结构，使Qoder Agent在生成或修改代码时能主动调用本地检查器，而非依赖提示词记忆隐式规范。
1、在项目根目录下建立harness/目录，包含constraints.yaml（定义禁止跨层import规则）、linter-config.json（指定pylint+custom-checks）。
2、创建codebase/目录替代传统src/，其下仅允许存在domains/、shared/、adapters/三级，禁止直接放置.py文件。
3、在shared/中存放types/、errors/、utils/等无业务状态的纯函数模块，并在harness/constraints.yaml中声明“codebase/shared/** must not import codebase/domains/**”。
4、运行qoder harness setup，自动挂载pre-commit hook与CI阶段的qoder validate --policy harness/constraints.yaml。
5、在Qoder IDE中启用“Harness Mode”，所有行间对话（Inline Chat）将默认加载harness/下的约束文件作为推理上下文。
三、MCP扩展优先的插件化结构
当项目需高频集成外部服务（如数据库Schema、API网关、向量库）并通过MCP协议暴露给Qoder Skill调用时，该结构将资源接入逻辑与业务逻辑物理隔离，保障Skill可复用性与环境一致性。
1、在项目根目录下创建mcp/目录，内含schemas/（SQL DDL、OpenAPI YAML）、connectors/（database.py、llm_gateway.py）、tools/（shell scripts for data sync）。
2、在mcp/connectors/database.py中实现get_schema()方法，返回当前连接数据库的完整表结构字典，供Qoder SQL生成器实时感知。
代码编辑 CLI 工具集合：Cursor CLI（agent）和 Qoder CLI（qodercli），用于代码修改、重构、Code Review 及自动化代码任务。
3、在domains/payment/services.py中禁止硬编码SQL字符串，必须调用mcp.connectors.database.query()封装方法。
4、执行qoder mcp register --path mcp/，将整个mcp/目录注册为项目级MCP资源池，所有Skill可通过mcp://database/query访问。
5、在SKILL.md中声明requires: ["mcp://database", "mcp://llm-gateway"]，Qoder CLI将在执行前校验对应connector是否已注册并健康。
四、Qoder Quest任务导向型结构
适用于以Quest视图为开发主界面的团队，目录结构按长期运行任务（Quest）生命周期组织，每个Quest拥有独立可部署、可观测、可回滚的代码沙盒，天然支持多Agent协同与目标驱动交付。
1、在项目根目录下创建quests/目录，每个子目录代表一个Quest，如quests/user-onboarding-v2/、quests/billing-reconciliation/。
2、每个quests/{quest-name}/下必须包含plan.md（目标定义）、code/（当前迭代代码）、artifacts/（生成的API文档、测试报告）、state/（JSON格式的当前执行状态快照）。
3、在quests/user-onboarding-v2/code/中采用最小必要结构：entrypoint.py（Quest入口）、steps/（step_01_validate.py、step_02_create_profile.py）。
4、执行qoder quest start --name user-onboarding-v2，Qoder自动加载quests/user-onboarding-v2/下的plan.md并初始化state/。
5、所有steps/*.py文件顶部必须包含# QODER_QUEST_STEP: user-onboarding-v2/step_01_validate标记，用于Qoder IDE在Quest视图中精准定位与调试。
五、混合式分层：Domains + Harness + MCP联合结构
面向超大型企业级Qoder工程，需同时满足业务可维护性、AI可验证性与外部系统强感知能力，该结构通过明确层级职责划分，杜绝各维度关注点相互污染。
1、项目根目录下并列存在domains/、harness/、mcp/、quests/四个顶级目录，禁止交叉引用。
2、domains/仅允许引用shared/与mcp/connectors/中的稳定接口，禁止直接import mcp/schemas/或harness/constraints.yaml。
3、在harness/policy/下定义domain-import-rules.yml，声明“domains/user/* may import shared/types but not domains/payment/*”，并由qoder validate自动校验。
4、所有mcp/下的connector实现必须通过harness/test-mcp-connectors.py进行契约测试，失败则阻断Quest启动。
5、每个quests/{name}/code/目录内不允许新增任何domains/外的业务逻辑，仅允许orchestrate已有domains模块与mcp工具链。
