composer.json 本身就是权威依赖文档，因其直接驱动安装、自动加载和版本约束，且字段语义明确；readme.md 只需补充关键依赖用途、特殊配置要求、自定义命名空间映射及私有仓库说明。
不需要专门写 Composer 依赖管理文档——composer.json 本身就是可执行、可验证、机器可读的权威文档。 手动维护一份脱离 composer.json 的“教程式”依赖说明，反而容易过时、与实际不一致，还会增加协作成本。
为什么 composer.json 比任何 Markdown 文档都更可靠
它直接驱动安装、更新、自动加载和版本约束行为，所有字段都有明确语义：
-
require和require-dev明确区分运行时与开发期依赖，且包含精确版本约束（如"monolog/monolog": "^2.10"） -
autoload和autoload-dev定义了类如何被加载，是 PSR-4 自动加载的事实来源 -
conflict、provide、replace等字段表达包间兼容性逻辑，Markdown 很难准确传达这种约束关系 - 运行
composer show或composer depends vendor/package可实时查依赖树，比静态文档更可信
哪些信息必须补充在 README.md 里（而非另写“依赖文档”）
用户真正需要知道的，不是“用了哪些包”，而是“怎么用、为什么用、有什么限制”。这些应简明写在项目 README.md 中：
Discussion Composer
下载
围绕关键发现、作用机制、临床相关性及研究局限性展开讨论。适用于撰写或优化任何生物医学论文的“讨论（Discussion）”部分——包括结果解读、与既往文献关联、阐释意外发现、界定研究局限性，以及撰写结论。当用户输入以下任一指令时也会自动触发该功能： - “write my discussion” - “help me discuss my findings” - “how do I compare to prior studies” - “write the limitations par
- 列出关键依赖的用途，例如：
"phpunit/phpunit"仅用于test脚本，不参与生产流程 - 注明有特殊配置要求的包，比如：
"ext-redis"必须启用，或"guzzlehttp/guzzle"需要 PHP 8.1+，否则composer install会失败 - 说明自定义 autoloading 的命名空间映射（如
"App\Tests\": "tests/"），这对新协作者理解目录结构很关键 - 如果使用了
repositories（如私有 Git 包），务必写清来源和认证方式，否则别人composer install会卡住
常见错误：把 composer.lock 当作文档来解读
composer.lock 是锁文件，不是设计文档。它记录的是某次安装时解析出的具体版本快照，包括哈希值和平台配置。它的作用是保证重复安装结果一致，不是给人阅读的：
- 不要在 README 中截图或复制
composer.lock里的依赖列表——它随每次composer update变动，极易失效 - 不要试图从
lock文件反推“应该装什么”，一切约束逻辑必须源自composer.json - CI 流程中应校验
composer.lock是否过期（用composer validate --locked），而不是人工检查内容
真正重要的，是让 composer.json 字段清晰、注释得当（Composer 支持 JSON 注释）、约束合理；其余说明，一句话讲清场景，一行命令贴准示例，就够了。
