---

一、方案结论

AI 原生代码仓库包含五类工程资产：

工程资产	回答的问题	唯一存放位置
项目规则	AI 和研发必须遵守什么	AGENTS.md
项目知识	系统结构、业务含义和设计依据	docs/
可执行流程	一件重复工作具体怎样完成	.agents/skills/
工程实现	系统真正怎样运行	代码、配置和数据库变更
强制证据	怎样证明变更正确且不再复发	测试、Lint、CI、Hook、监控

仓库根目录统一使用 AGENTS.md、CLAUDE.md、docs/ 和 .agents/skills/。不同模型共享同一套规则、知识、Skill 和工程门禁。

---

二、规范原则

2.1 单一事实源

项目规则      → AGENTS.md
项目知识      → docs/
项目Skill     → .agents/skills/
确定性执行    → scripts/、代码和配置
强制校验      → 测试、Lint、CI、Hook和服务端规则

同一事实只维护一份，其他文件通过路径引用。

2.2 渐进式加载

• AGENTS.md 只包含启动必需的规则、命令和导航。
• docs/ 按架构、领域、模块和问题分类，任务命中后读取。
• Skill 启动时只暴露名称和描述，命中后读取完整 SKILL.md。
• 脚本和参考资料只在执行到对应步骤时加载。

2.3 多模型兼容

模型	项目入口	Skill位置	兼容方式
Codex	AGENTS.md	.agents/skills/	原生读取和发现
Claude Code	CLAUDE.md	.agents/skills/	CLAUDE.md 引用统一入口并指示查找
其他模型	AGENTS.md	.agents/skills/	按项目入口导航读取

项目规则、知识和 Skill 均以 Codex 目录规范为准。模型适配文件只负责导航，不复制正文。

2.4 工程能力分工

• Skill 负责工作流选择、判断和编排。
• Script 负责可重复、确定性的执行步骤。
• MCP 和 OpenAPI 负责访问外部系统。
• 测试、CI、Hook 和服务端规则负责强制校验。
• 项目在没有 AI 工具时仍必须能够构建、测试、发布和回滚。

---

三、标准代码仓库目录

project-root/
├── AGENTS.md                         # Codex及其他Agent统一规则入口
├── CLAUDE.md                         # Claude Code薄适配入口
├── README.md                         # 面向人的项目首页
│
├── .agents/
│   └── skills/                       # 项目专属Skill唯一源
│       ├── project-start-backend/
│       │   ├── SKILL.md
│       │   ├── scripts/
│       │   ├── references/
│       │   └── assets/
│       └── project-release-check/
│           └── SKILL.md
│
├── docs/                             # 项目知识唯一事实源
│   ├── README.md                     # 知识导航
│   ├── architecture/                 # 总体架构和关键链路
│   ├── domain/                       # 领域模型和业务规则
│   ├── modules/                      # 模块职责、依赖和边界
│   ├── api/                          # 接口契约和集成说明
│   ├── adr/                          # 架构决策记录
│   ├── troubleshooting/              # 高价值Bug和排障经验
│   ├── runbooks/                     # 人工运维和应急手册
│   ├── changelogs/                   # 迭代发布公告
│   │   └── yyyy-MM-dd/
│   │       └── index.md
│   ├── standards/                    # 项目级研发标准
│   └── glossary.md                   # 术语表
│
├── src/                              # 生产代码
├── tests/                            # 自动化验证
├── scripts/                          # 人与Agent共用的确定性脚本
├── config/                           # 非敏感配置模板
└── .gitlab-ci.yml                    # GitLab CI/CD质量门禁

3.1 项目可以增加子目录 AGENTS.md

大型单体仓库或多模块仓库可以在子目录增加局部规则：

project-root/
├── AGENTS.md
├── backend/
│   ├── AGENTS.md
│   └── src/
└── frontend/
    ├── AGENTS.md
    └── src/

原则：

• 根目录规则适用于整个仓库。
• 子目录规则只描述该模块的差异。
• 子目录不得复制根目录完整内容。
• 离当前代码更近的规则优先。

---

四、各类资产的边界

这是本规范最重要的判断表。

内容	正确位置	不应放的位置
所有变更必须执行哪些测试	AGENTS.md	普通知识文档
系统架构及设计依据	docs/architecture/、docs/adr/	Skill
模块负责什么、依赖谁	docs/modules/	AGENTS.md 大段正文
如何重复创建提测单	.agents/skills/	Bug 文档
如何人工处理线上故障	docs/runbooks/	AGENTS.md
一次高价值 Bug 的根因	docs/troubleshooting/	单独创建一个低频 Skill
迭代发布内容和用户影响	docs/changelogs/yyyy-MM-dd/index.md	Skill 或聊天记录
可重复的排障流程	.agents/skills/	只记录在聊天中
防止同类 Bug 复发	测试、Lint、CI、监控	只写文档
API Token、密码、Cookie	密钥系统、环境变量	代码、Skill、文档
当前会话的临时猜测	当前任务上下文	项目长期知识库
跨项目通用 Skill	团队 Skill 市场	每个业务仓库复制一份
只对当前仓库有效的 Skill	.agents/skills/	团队公共市场

4.1 一条快速判断路径

这是项目必须长期遵守的硬规则吗？
  是 → AGENTS.md

这是关于系统结构、业务含义或设计原因的事实吗？
  是 → docs/

这是一个可以重复执行、有明确步骤和结果的工作流吗？
  是 → .agents/skills/

这是必须百分之百阻止违规的约束吗？
  是 → 测试、CI、Lint、Hook或服务端校验

这是一次性的调查、猜测或聊天结论吗？
  是 → 不进入仓库，验证后再分类沉淀

---

五、AGENTS.md 规范

5.1 应该包含什么

根目录 AGENTS.md 只包含：

1. 项目定位和技术栈摘要。
2. 关键目录导航。
3. 构建、测试、Lint 和验证命令。
4. 不得违反的代码和安全规则。
5. 项目 Skill 的发现与使用规则。
6. 文档更新条件。
7. MR 和 Review 要求。

5.2 不应该包含什么

• 完整业务需求说明。
• 数百行接口字段。
• 大段数据库结构。
• 每个模块的所有实现细节。
• 历史 Bug 全文。
• 临时任务计划。
• 个人偏好和与项目无关的知识。

5.3 推荐模板

# Project Agent Instructions

## 项目定位

本项目负责……

## 启动顺序

1. 阅读本文件。
2. 阅读 `docs/README.md`。
3. 根据任务读取相关模块、架构、ADR或排障文档。
4. 检查 `.agents/skills/` 中是否存在匹配的项目Skill。

## 关键目录

- 生产代码：`src/`
- 测试代码：`tests/`
- 项目知识：`docs/`
- 项目Skill：`.agents/skills/`
- 确定性脚本：`scripts/`

## 必须遵守

- 不得提交Token、密码、Cookie和私钥。
- 修改生产逻辑必须补充或更新测试。
- 不得删除失败测试来让流水线通过。
- 修改业务行为时检查对应`docs/`是否需要更新。
- 修复高价值Bug时必须增加防复发措施。

## 验证命令

- 构建：`...`
- 单元测试：`...`
- 静态检查：`...`
- 集成测试：`...`

## Skill使用

- 项目Skill统一存放在`.agents/skills/`。
- 任务与Skill描述匹配时，完整读取对应`SKILL.md`后执行。
- 不创建`.claude/skills/`副本。
- 跨项目通用能力优先从团队Skill市场安装。

## 知识更新

- 架构决策变化：更新`docs/adr/`。
- 模块职责变化：更新`docs/modules/`。
- 高价值Bug：更新`docs/troubleshooting/`。
- 迭代发布：更新`docs/changelogs/yyyy-MM-dd/index.md`。
- 可重复流程：新增或更新Skill。

---

六、CLAUDE.md 兼容规范

CLAUDE.md 必须保持轻量，只做模型适配，不能形成第二套项目规则。

推荐模板：

@AGENTS.md

# Claude Code Compatibility

本仓库以Codex兼容目录作为唯一规范和事实源。

## 统一入口

- 项目规则：`AGENTS.md`
- 项目知识：`docs/`
- 项目Skill：`.agents/skills/`
- 确定性脚本：`scripts/`

## Skill发现方式

Claude Code执行任务前：

1. 检查`.agents/skills/*/SKILL.md`的`name`和`description`。
2. 如果任务与某个Skill匹配，完整读取该`SKILL.md`。
3. 按照Skill中指向的`scripts/`、`references/`和`assets/`继续执行。
4. 不创建或维护`.claude/skills/`副本。

## 事实源规则

- 不在本文件复制`AGENTS.md`规则。
- 不在本文件复制`docs/`业务知识。
- 不为Claude单独维护业务流程。

---

七、docs/ 知识库规范

7.1 docs/ 的职责

docs/ 记录项目长期有效且已经验证的知识，包括：

• 系统边界；
• 业务概念；
• 模块职责；
• 接口契约；
• 架构决策；
• 故障模式；
• 运维手册；
• 迭代发布记录；
• 研发标准；
• 关键术语。

7.2 docs/README.md 必须充当知识地图

示例：

# 项目知识导航

## 新人入门

- 系统概览：`architecture/overview.md`
- 本地启动：`runbooks/local-development.md`
- 术语表：`glossary.md`

## 按模块

- 用户权限：`modules/user-permission.md`
- 提测管理：`modules/test-plan.md`
- Multica集成：`modules/multica-integration.md`

## 按问题

- 架构决策：`adr/`
- 常见故障：`troubleshooting/`
- 运维操作：`runbooks/`
- 迭代公告：`changelogs/`

7.3 文档分类边界

目录	内容	示例
architecture/	系统整体关系和关键链路	请求链路、部署架构
domain/	业务实体、状态和规则	Issue状态、提测单规则
modules/	模块职责和依赖	TestPlan模块说明
api/	对外接口契约	OpenAPI请求与返回
adr/	关键方案选择及依据	事件驱动方案决策
troubleshooting/	高价值问题的根因和识别方法	成员匹配失败
runbooks/	人工操作和应急处理	回滚、扩容、数据修复
changelogs/	迭代发布内容、影响和使用规则	2026-08-05版本公告
standards/	项目级研发约束正文	日志、异常、SQL规范

7.4 文档准入条件

只有满足以下条件之一的内容才进入 docs/：

• 后续开发需要依赖该知识做正确判断。
• 新成员需要该知识才能理解项目。
• 错误理解该知识可能造成缺陷或事故。
• 该结论已经由代码、测试、接口或 Owner 验证。
• 该知识具有长期价值，不只是当前任务的过程记录。

以下内容不得进入长期知识库：

• 未验证猜测；
• 聊天过程全文；
• 临时命令输出；
• 很快过期的个人待办；
• 与项目无关的通用知识；
• 可直接从代码简单读出的无价值复述。

7.5 Changelog 规范

迭代公告统一存放在：

docs/changelogs/yyyy-MM-dd/index.md

每份公告至少包含：

• 发布日期和版本；
• 新增功能；
• 优化功能；
• 缺陷修复；
• 用户可见的业务规则；
• 配置、兼容性和使用注意事项；
• 必要的截图、GIF或关联Issue。

根目录 CHANGELOG.md 为可选文件；存在时只维护版本索引并链接到 docs/changelogs/，不得复制公告全文。

推荐模板：

# yyyy-MM-dd 版本公告

## 新增功能

- 功能名称、适用范围和使用规则。

## 优化功能

- 优化内容和用户影响。

## 缺陷修复

- 修复的问题和影响范围。

## 配置与注意事项

- Apollo、数据库、权限或兼容性要求。

---

八、Skill 规范与边界

8.1 什么是 Skill

Skill 是一套能够被 Agent 按需加载的可重复工作流，应该具有：

• 明确触发场景；
• 明确输入；
• 明确执行步骤；
• 明确输出；
• 明确验证方式；
• 明确权限和失败处理；
• 必要时包含脚本、参考资料和输出素材。

8.2 什么不是 Skill

以下内容不应该单独做成 Skill：

• 一次性任务说明；
• 普通知识文章；
• 单个低价值 Bug 记录；
• 单纯的代码规范；
• 一个没有工作流的 API 字段列表；
• 只对个人有意义的提示词；
• 本应由 CI 强制执行的规则；
• 把多个不相关任务强行打包成的万能 Skill。

8.3 项目 Skill 和市场 Skill

判断问题：离开当前代码仓库后，它是否仍然有意义？

类型	存放位置	示例
项目专属 Skill	当前仓库 .agents/skills/	FTD启动后端、FTD维护Changelog
团队共享 Skill	Jone Marketplace	创建Task、创建MR、创建提测单
个人 Skill	用户本机 ~/.agents/skills/	个人日报、个人写作偏好

项目仓库不复制公共 Skill。公共 Skill 通过团队市场安装到用户目录。

8.4 标准 Skill 结构

.agents/skills/project-release-check/
├── SKILL.md                    # 必需：触发条件和核心流程
├── scripts/                    # 可选：确定性执行脚本
├── references/                 # 可选：任务专用参考资料
├── assets/                     # 可选：模板、图片、样例
└── agents/
    └── openai.yaml             # 可选：Codex界面元数据

SKILL.md 最小模板：

---
name: project-release-check
description: 检查当前项目是否满足发布条件。当用户提出发版、上线、发布检查或生成发布清单时使用。
---

# 发布检查

## 输入

- 当前分支
- 目标环境
- 发布版本

## 步骤

1. 检查工作区和分支状态。
2. 执行构建、测试和安全扫描。
3. 检查配置变更和回滚方案。
4. 检查Changelog。
5. 输出阻塞项和发布建议。

## 验证

- 所有命令必须返回成功。
- 不得跳过失败测试。
- 不得输出或保存密钥。

8.5 Skill 的渐进式加载

Skill 应按照三层组织上下文：

第一层：name + description
用于判断是否命中，必须短而准确

第二层：SKILL.md正文
命中后加载，只写核心工作流

第三层：scripts、references、assets
执行到对应步骤时按需使用

要求：

• SKILL.md 保持聚焦，原则上不超过 500 行。
• 详细接口和业务背景引用 docs/，不要复制。
• 大型参考资料拆入 references/，并在 SKILL.md 中写明何时读取。
• 确定性、重复编写的逻辑优先形成脚本。
• 引用层级保持简单，避免引用文件继续无限引用。

8.6 Skill 不得成为秘密和权限容器

不得在 Skill 中保存：

• Token；
• Cookie；
• 密码；
• 私钥；
• 生产数据库账号；
• 可绕过审批的固定参数。

Skill 只能说明凭证从哪里安全获取。真实权限必须由 MCP、OpenAPI、IAM、审批系统或密钥平台控制。

---

九、历史 Bug 的沉淀边界

9.1 默认先进入 docs/troubleshooting/

历史 Bug 首先是一条经过验证的项目知识，应该记录：

• 现象；
• 影响范围；
• 触发条件；
• 根本原因；
• 修复方案；
• 验证方式；
• 防复发措施；
• 关联 Issue、MR、测试和 ADR。

推荐模板：

# 问题名称

## 现象

用户看到什么，系统发生什么。

## 影响范围

影响哪些模块、版本、用户和环境。

## 触发条件

在什么数据、状态或调用顺序下出现。

## 根本原因

说明失效的系统契约，而不是只写修改了哪一行。

## 修复方案

说明代码、配置或数据怎样修改。

## 验证证据

- 自动化测试：
- 日志或监控：
- 回归场景：

## 防复发措施

- 新增测试：
- 新增门禁：
- 新增监控：
- 是否需要Skill：

9.2 什么时候从 Bug 文档提炼为 Skill

满足以下任一条件，可以提炼为排障 Skill：

• 同类问题出现两次以上。
• 排查需要多个固定步骤。
• 需要重复查询日志、数据库、配置和接口。
• 不同研发人员的排查结果经常不一致。
• 排查过程可以脚本化。
• 错误操作可能扩大生产影响。

例如：

docs/troubleshooting/multica/member-match-failed.md
    记录一次真实问题的现象、根因和修复

.agents/skills/project-troubleshoot-multica/
    提供可重复执行的Multica排查流程

tests/
    防止成员匹配逻辑再次回归

9.3 Bug 沉淀不是四选一

Bug事实和根因       → docs/troubleshooting/
可重复排查流程      → Skill
永久防复发          → 测试、CI、Lint、监控
所有开发必须遵守    → AGENTS.md

普通低价值 Bug 保留在 Issue 和 MR 即可，避免制造文档噪声。

---

十、Skill、Runbook、脚本和 CI 的边界

资产	使用者	特点	示例
Skill	AI Agent	有判断、有编排、按需加载	创建提测单
Runbook	人和AI	解释人工操作、应急决策和回滚	生产故障处理
Script	人和AI	确定性执行、参数明确	检查配置差异
CI/Hook	系统	自动强制、不可依赖自觉	Secret扫描
MCP/OpenAPI	Agent和系统	受控访问外部系统	创建Issue

推荐组合：

Skill
  → 阅读相关docs或Runbook
  → 调用scripts执行确定性步骤
  → 通过MCP/OpenAPI访问外部系统
  → 由CI和服务端规则保证安全边界

错误做法：

• 在 Skill 里复制整个 Runbook。
• 在 Skill 里重新实现已有脚本。
• 用提示词代替权限校验。
• 用文档要求代替 CI 门禁。
• 用 AI 记忆代替项目事实源。

---

十一、研发端到端工作方式

11.1 开始任务

1. 从 Issue 获取目标、范围、验收条件和依赖。
2. Agent 自动读取 AGENTS.md。
3. Claude Code 通过 CLAUDE.md 引用同一套规则。
4. 读取 docs/README.md，定位相关模块知识。
5. 检查 .agents/skills/ 是否存在匹配工作流。
6. 形成包含验证和回滚的实施计划。

11.2 实现任务

1. 优先复用现有代码、脚本和 Skill。
2. 小步修改，避免无关重构。
3. 每完成一个稳定单元就运行相关测试。
4. 业务行为变化时同步更新知识事实源。
5. 不把临时猜测写入长期文档。

11.3 提交前分类判断

代码行为是否变化？
  → 检查模块和API文档

是否产生新的架构选择？
  → 新增或更新ADR

是否修复高价值Bug？
  → 增加测试和troubleshooting文档

是否形成重复流程？
  → 新增或更新项目Skill

是否发现跨项目通用能力？
  → 先在项目验证，再申请晋升Skill市场

11.4 提交 MR

MR 必须同时交付：

• 代码变更；
• 测试证据；
• 必要的文档更新；
• 必要的 Skill 更新；
• 配置和数据变更说明；
• 风险和回滚方案。

---

十二、工程质量门禁

AI 生成代码与人工代码使用同一套门禁：

12.1 本地门禁

• 编译或构建；
• 格式检查；
• 静态分析；
• 单元测试；
• Secret 扫描；
• 变更范围检查。

12.2 MR 门禁

• 完整构建；
• 核心测试；
• 依赖和漏洞扫描；
• 知识更新检查；
• Changelog 判断；
• 人工代码审查。

12.3 发布门禁

• 制品可追溯；
• 配置变更明确；
• 回滚路径有效；
• 监控和告警具备；
• 高风险动作已经审批。

任何门禁失败都必须返回修改阶段，不得通过删除测试、关闭扫描或吞掉异常绕过。

---

十三、角色职责

13.1 项目负责人

• 决定项目规则和高风险边界。
• 审批根目录 AGENTS.md 的重大变化。
• 确认项目知识 Owner。
• 决定项目 Skill 是否具备市场晋升价值。

13.2 架构师和模块 Owner

• 维护架构、模块知识和 ADR。
• 判断知识是否准确、长期有效。
• 审查 Skill 是否错误复制业务事实。
• 识别跨模块契约和风险。

13.3 研发

• 开始编码前加载规则和相关知识。
• 优先复用已有 Skill、脚本和抽象。
• 提交代码时同步交付测试和知识更新。
• 把高价值 Bug 形成可检索经验。

13.4 测试

• 将验收条件转化为可执行验证。
• 判断缺陷是否属于高价值模式。
• 确认防复发测试覆盖真实边界。
• 参与排障 Skill 的场景验证。

13.5 DevOps 和 SRE

• 将稳定发布和排障步骤沉淀为脚本与 Runbook。
• 对高风险 Skill 设置权限和审批。
• 保证发布、回滚、监控和告警可验证。

13.6 Reviewer

• 检查代码与文档是否一致。
• 检查 Skill 是否越界承担业务事实或权限。
• 检查测试是否真正覆盖根因。
• 识别 AI 常见的过度修改、虚构接口和无效异常处理。

---

十四、Skill 晋升团队市场规则

项目 Skill 满足以下条件后，才考虑进入 Jone Marketplace：

• 已经在真实项目中成功使用。
• 至少存在第二个项目的复用需求。
• 已去除项目路径、固定域名和业务硬编码。
• 输入、输出、权限和失败处理明确。
• 包含成功和失败场景验证。
• 有明确 Owner。
• 不包含敏感信息。
• 命名和描述不会与现有 Skill 冲突。

晋升流程：

重复操作出现
→ 项目Skill
→ 真实任务验证
→ 去除项目耦合
→ 补充测试和安全边界
→ Owner评审
→ 发布Jone Marketplace
→ 其他项目按需安装

市场 Skill 不复制回业务仓库。业务仓库如有特殊差异，可保留一个轻量项目适配 Skill，但不得复制市场 Skill 全文。

---

十五、知识保鲜和淘汰机制

15.1 文档保鲜

每份重要文档应具有：

• Owner；
• 适用模块；
• 最后验证时间；
• 关联代码或接口；
• 废弃条件。

在以下事件发生时检查文档：

• 模块重构；
• 接口变更；
• 状态机变化；
• 数据模型变化；
• 发布流程变化；
• 同类 Bug 再次发生。

15.2 Skill 保鲜

在以下事件发生时重新验证 Skill：

• 工具或接口升级；
• 目录结构变化；
• 权限模型变化；
• 构建和测试命令变化；
• 连续执行失败；
• 长期无人使用。

15.3 淘汰规则

以下内容应当删除或归档：

• 已被代码和测试完全替代的临时说明；
• 已不存在模块的文档；
• 已由市场 Skill 替代的项目复制品；
• 没有触发场景的空壳 Skill；
• 长期失效且无人维护的脚本；
• 与当前项目无关的个人知识。

---

十六、仓库准入检查清单

16.1 基础入口

• 根目录存在 AGENTS.md。
• 根目录存在轻量 CLAUDE.md。
• CLAUDE.md 引用 AGENTS.md，没有复制业务规则。
• 存在 docs/README.md 知识导航。
• 项目 Skill 统一放在 .agents/skills/。

16.2 知识边界

• 架构事实进入 docs/architecture/ 或 docs/adr/。
• 模块知识进入 docs/modules/。
• 高价值 Bug 进入 docs/troubleshooting/。
• 迭代公告进入 docs/changelogs/yyyy-MM-dd/index.md。
• 临时聊天内容没有直接提交为长期知识。
• 同一业务事实没有在多个位置复制。

16.3 Skill 边界

• Skill 有明确触发条件、输入、步骤、输出和验证。
• Skill 没有复制完整业务文档。
• Skill 没有保存 Token、Cookie、密码和私钥。
• 确定性重复逻辑已经形成脚本。
• 跨项目通用 Skill 没有被复制进业务仓库。

16.4 工程门禁

• AI 代码与人工代码执行相同测试。
• 高价值 Bug 有防复发测试或门禁。
• 构建、发布和回滚不依赖 AI 才能执行。
• 高风险操作由服务端权限和审批强制控制。
• MR 同时检查代码、知识、测试和 Skill 一致性。

---

十七、实施路线

第一阶段：建立入口

1. 创建根目录 AGENTS.md。
2. 创建只做适配的 CLAUDE.md。
3. 创建 docs/README.md 和标准知识目录。
4. 清理重复、失效和无 Owner 的旧文档。

第二阶段：沉淀项目经验

1. 选择三个高频重复流程形成项目 Skill。
2. 选择三个高价值历史 Bug 形成 troubleshooting 文档。
3. 为这些 Bug 增加防复发测试。
4. 把确定性流程提取到 scripts/。

第三阶段：形成团队复用

1. 识别至少被两个项目需要的 Skill。
2. 去除项目耦合并发布到 Jone Marketplace。
3. 建立 Skill Owner、Review 和安全准入。
4. 通过真实使用数据持续优化 Skill。

第四阶段：建立治理度量

建议关注：

• 新成员理解项目所需时间；
• Agent 首次任务成功率；
• 因知识过期导致的返工次数；
• 同类 Bug 复发次数；
• Skill 调用成功率；
• Skill 平均节省时间；
• 公共 Skill 跨项目复用数量；
• AI 代码导致的回滚和事故数量。

---

十八、官方参考

• OpenAI：Custom instructions with AGENTS.md
• OpenAI：Build Skills
• Agent Skills 开放规范
• Anthropic：Claude Code Skills
• Anthropic 官方 Skills 仓库

---

十九、最终原则

团队只需要长期坚持下面七条：

1. 规则进入 AGENTS.md。
2. 知识进入 docs/。
3. 项目流程进入 .agents/skills/。
4. Claude 通过 CLAUDE.md 使用同一套事实源。
5. 跨项目 Skill 进入团队市场，不复制进业务仓库。
6. Bug 必须通过测试和门禁防复发，不能只停留在文档。
7. 安全、权限和质量必须由工程系统强制执行，不能只依赖提示词。

AI 原生代码仓库的目标，不是让模型读更多文件，而是让任何研发和任何模型都能快速找到正确规则、正确知识、正确流程和正确验证方式。