.maw 协作协议

.maw/ 是 Seed 放置项目协作协议的目录。它用结构化文件描述项目身份、组件、模块、环境、发布、仓库、能力、项目信号和安全边界，帮助 AI 在动手前先读到稳定事实。

它不是业务源码，也不是私密配置仓库。真实密钥、本机覆盖和一次性资料不应该提交进 .maw/ 的公共文件。

常见文件

文件	用途	什么时候更新
.maw/project.yaml	项目 key、名称、协作模式、默认分支和基础边界。	初始化项目或项目身份变化时。
.maw/components.yaml	前端、后端、脚本等组件清单和路径。	新增、删除或重命名组件时。
.maw/modules.yaml	模块树、模块档案、页面/API/配置/测试边界。	页面、接口、数据或模块边界变化时。
.maw/capabilities.yaml	可复用能力、脚本、协议和数据契约索引。	新增公共能力或复用能力时。
.maw/project-signals.yaml	澄清、风险、缺口、待办引用和 AI 前置提示。	发现影响后续协作的信息时。
.maw/repository-identity.yaml	仓库角色、公开边界和同步约束。	仓库角色或交付方式变化时。
.maw/environments.yaml	环境、运行位置和发布目标的结构化说明。	本地、测试或生产环境规则变化时。
.maw/releases.yaml	发布环境、快捷发布口令和版本策略。	发布流程或组件发布范围变化时。
.maw/policies.yaml	脱敏、边界和提交检查策略。	安全策略变化时。
.maw/health/	项目健康、事实、决策、关注事项和验收缺口。	项目状态需要轻量记录时。

读取原则

1. 任务开始先读相关配置，不直接全仓搜索。
2. 结构化文件优先于旧文档，当前代码事实优先于过期说明。
3. 本机差异只读 .local/ 或本机覆盖文件，不写入公共文档。
4. 对不确定事实标记待确认，不编造模块、环境或密钥。
5. 修改配置后运行对应检查。

最小配置示例

project:
  key: my_project
  name: My Project
  default_branch: main
collaboration:
  ai_coding: true
  public_docs_use_relative_paths: true

components:
  - key: client
    name: Web Client
    path: code/client
  - key: server
    name: API Server
    path: code/server

真实项目可以继续拆分到 .maw/<domain>.d/*.yaml，但公共文档只需要说明稳定结构和读取方式。

配置和文档的关系

• .maw/ 保存机器可读事实。
• docs/ 保存人可读说明和决策背景。
• ops/ 保存读取、检查和发布脚本。

当三者冲突时，先看当前源码和聚合后的 .maw 配置，再修正文档。

下一步

阅读 配置文件，查看常见 .maw 文件的使用清单。