Gogs 仓库的 AGENTS.md 工程协作规范全解读从编码到提交的完整开发约定【免费下载链接】gogsThe painless way to host your own Git service项目地址: https://gitcode.com/GitHub_Trending/go/gogs说明本文将基于 AGENTS.md 这份仓库级开发协作手册结合 Gogs自托管 Git 服务当前仓库的实际源码、构建配置与测试代码逐条解读其对 AI 开发助手与人类开发者提出的工作准则包括核心协作原则、Go 与前端编码规范、本地化流程、可访问性要求、构建与代码提交纪律。读者读完可以掌握在该仓库中高效协作的正确姿势以及每条规范背后的仓库实现依据。一、AGENTS.md 是什么给代码协作者的“行动总纲”在 Gogs 仓库根目录中AGENTS.md 是一份面向代码编写者尤其是 AI Agent的工程协作手册。它与普通的贡献指南不同内容高度浓缩条条都是可执行的硬性约束覆盖了从“接到任务后如何推进”到“写错代码时如何自纠”再到“文案、国际化、UI、提交”的全链路约定。该文件与仓库中其他文档如 web/DESIGN.md形成“总纲 细则”的关系AGENTS.md 负责定义适用于全仓库的通用规则并引用专门的模块文档作为补充约束。理解它等同于理解这个仓库当前被期望如何被维护。二、核心协作原则一次做对尊重现状文档开篇即强调两条贯穿始终的核心原则停止无意义的附和一次做对不要用“你说得对”这类空话回应而要在第一次尝试时就做正确并在改动后进行事实核查与自我复查如果不确定就主动求助。以当前版本为新的起点当发现超出自己知识范围的既有改动时不要盲目覆盖而是把它当作新起点尊重周边上下文中已经形成的模式。这两条原则的实际价值在于Gogs 是一个长期演进的成熟代码库覆盖cmd/、internal/下的 app、auth、context、database、route、repo 等大量子包以及web/前端工程任何机械化的“重写式”改动都极易破坏既有约定。文档明确要求 Agent 在改动前先以现有代码为锚点改动后先自查再交付这与仓库中大量配套测试例如 internal/database 下几乎每个模块都有同名_test.go的工程质量要求是一致的。三、Style and mechanics全仓库通用文案规则该规范适用于所有面向用户的文本包括但不限于 UI 文案、文档与代码注释。核心规则包括采用 sentence case句首大写、其余小写但品牌名保留原始大小写完整句子必须以句号结尾正文中禁止使用 em dash—与 en dash–应改写为逗号、句号、冒号或括号唯一的例外是作为 UI 设计中的视觉分隔符例如标题与描述之间不要过度使用分号两个短句通常比一个用分号连接的长句更清晰仅当两个子句耦合极强、拆分会丢失含义时才使用分号注释应解释代码无法直接表达的意图而不是复述代码行为优先使用更具描述性的命名。此规则优先于“跟随既有模式”CHANGELOG 条目只描述用户视角的可见影响不写入实现细节可对照仓库根目录的 CHANGELOG.md 的写作风格使用e.g.,与i.e.,时必须带尾随逗号。这些细节对中文社区团队同样有借鉴意义在提交信息、Release 说明与界面文案上保持一致的句式风格能显著降低多语言维护与后续机器翻译的成本。四、Coding guidelinesGo 侧的三条硬规范4.1 错误处理统一使用cockroachdb/errors文档规定所有 Go 代码的错误处理统一使用github.com/cockroachdb/errors。该要求与当前仓库的依赖声明完全一致go.mod 第 9 行声明了github.com/cockroachdb/errors v1.13.0。从源码看这一约定已被大面积落实。例如在 internal/database 的actions.go、attachment.go、comment.go、database.go、issue.go等实现中均大量使用errors.New、errors.Wrap系列调用为错误链保留原始上下文。选用该库的价值在于其丰富的堆栈信息保留能力便于在 Gogs 这类需要精确追踪数据库与 Git 操作失败原因的服务端代码中快速定位根因。4.2 测试断言统一使用stretchr/testify测试必须使用github.com/stretchr/testify进行断言同时要审慎选择require与assert当断言失败后测试无法继续有意义地执行时应当使用require立即终止反之才使用assert继续执行。该约定同样有仓库证据支撑go.mod 第 45 行声明github.com/stretchr/testify v1.11.1典型示例如 internal/database/access_tokens_test.go其中大量使用assert.Equal、assert.True、assert.False组合校验 token 的时间戳与使用状态字段。选择assert而非require的场景通常是同一实体多个字段的独立校验单点失败不影响其他断言继续执行反之若后续断言依赖前一步结果则应使用require尽早暴露问题。4.3 5xx 错误必须在 handler 内直接记录日志文档规定每一个 5xx 响应都必须在 handler 内部直接记录错误日志不要在共享 helper 中统一打日志。从源码结构看这正对应 internal/context/context.go 提供的Error、NotFoundOrError等上下文方法路由层在调用它们时同时传入人类可读的描述例如 internal/route/home.go 中的c.Error(err, search repository by name)从而让错误日志携带具体的业务语义而不是在底层共享封装里打出一堆无法区分场景的堆栈。这种“语义化日志下沉到调用点”的模式直接服务于 Gogs 生产环境下的问题定位效率。五、Localization本地化文件的“编辑主权”边界本地化是 Gogs 这类国际化项目的高频改动点文档给出了明确的权限边界只能编辑 conf/locale/locale_en-US.ini英文基准语言文件其他locale_*.ini由社区维护严禁增删或改写其中的键即使是删除 Go/模板侧已经失效的死键也不允许。仓库现状与该约定吻合conf/locale/目录下共存有 32 个语言文件含locale_zh-CN.ini、locale_ja-JP.ini、locale_ko-KR.ini等其中locale_en-US.ini是唯一由主仓库维护者直接掌管的基准源。这条规则的工程意义在于避免主分支与社区翻译仓库之间因键名不一致产生合并冲突保证自动化提取与回填流程可参考 web/scripts/extract-locales.mjs 这类脚本的同步基础永远以 en-US 为准。六、UI guidelines移动优先与无障碍底线前端工作必须遵守三条相辅相成的约束移动优先设计每个 UI 都必须在窄视口下先做好做对再通过响应式断点增加桌面端精化在约375px宽度下验证通过才能视为完成。至少满足 WCAG 2.2 AA具体量化要求包括每个交互控件都有可辨识的可访问名称可见 label 或aria-label颜色不能作为信息的唯一载体必须配文字、图标或形状正文与有意义图标相对背景满足4.5:1对比度大号文字与 UI 组件为3:1焦点始终可见且不会被困住触摸目标至少24×24 CSS px优先40×40。拿不准时宁可选择更高对比度、更大目标与更明确的标签。web/下的工作必须遵循 web/DESIGN.md中记录的排版、颜色层级、表面装饰、文件命名与无障碍细则当一个模式在两处被使用时就应当回写更新该文档。6.1 服务端数据的获取位置route loader 而非 useEffect文档对数据获取给出了一条非常具体的前端架构约束当页面需要服务端数据渲染时必须在 TanStack Router 路由的loader中获取让页面只在响应返回后才挂载严禁在页面组件内部用useEffect触发该请求否则会造成数据到达前先闪烁出空 UI。该约束在仓库中有清晰的实现对应web/src/router.tsx 基于 TanStack Router 构造路由树createRootRouteWithContext、createRoute并为根路由配置defaultErrorComponent: ServerError而 web/src/routes/repo.tsx 就是典型实践其路由节点定义了loaderDeps与异步loader在 loader 内完成请求并发起错误响应例如返回 404 而不浪费一次拉取。仓库中 web/src/pages/NotFound.tsx、web/src/pages/ServerError.tsx 等组件则承担路由错误渲染。七、Build instructions用 moon 统一构建与质量门禁当前仓库的前后端构建统一通过 moonrepoGo 后端项目 id 为gogs与 web/moon.ymlTypeScript 前端项目 id 为web定义了全套任务。文档要求尽量使用moon run project:task而不是裸的go/pnpm命令例如moon run gogs:build、moon run web:dev需要绕过缓存时传入--force改完 Go 代码后必须运行moon run gogs:lint改完前端代码后运行moon run web:lint并修复全部 linter 错误。两个 moon 配置文件中的关键任务对应关系整理如下任务后端moon.yml前端web/moon.yml安装依赖installgo mod tidygo generate ./...installpnpm install在工作区根执行格式化formatgolangci-lint fmtformatpnpm run formatLintlintgolangci-lint runlintpnpm run lint测试testgo test -cover -race ./...—构建buildgo build -v -trimpath并注入BuildTime/BuildCommit到.bin/gogsbuildpnpm run build输出到/public/dist开发运行servercd .bin ./gogs webdevpnpm run dev全量产物build-prod以-tags prod构建依赖web:build被后端build-prod依赖值得注意的实现细节build任务通过-ldflags -X gogs.io/gogs/internal/conf.BuildTime... -X ...BuildCommit...把编译时间与当前 commit 注入internal/conf包这意味着每次构建产物的版本信息都可在运行时追溯而build-prod会额外携带-tags prod并串联前端web:build构成前后端一致的生产构建链路。此外根 moon.yml 还提供了portless、dev、prod等组合任务用于把本地服务暴露到gogs.localhost开发域名。八、Tool-use guidance 与 Source code control工具纪律与提交纪律8.1 工具使用访问 GitHub 上非公开的信息时使用ghCLIChrome DevTools MCP 必须以 headless 模式运行避免抢走用户前台浏览器焦点任务结束后用pkill -f chrome-devtools-mcp清理所有残留进程。8.2 源码控制纪律从 fork 推送 PR 变更时使用 SSH 地址且不要添加 remote除非被明确要求绝不直接提交到main分支一次“允许”只对应 main 分支上的一次提交动作绝不擅自 amend 提交除非被明确要求创建 git worktree 时worktree 目录名必须与其分支名一致不得使用随机或生成的后缀。最后一条对多分支并行开发极具实操价值目录名 分支名的约定让本地多个 worktree 之间可以靠路径名直接辨别分支归属避免gogs-fix-a1k2这类无法识别的随机目录堆积。结合“不直推 main”“不 amend”两条纪律可以推断该仓库期望的协作流是功能分支或 fork 分支 → 提交 → PR 审查合并历史保持线性与可追溯。九、小结把规范变成可执行的协作清单将 AGENTS.md 的要点压缩为 AI 助手与贡献者的每日行动清单改动前先读周边代码以当前实现为起点改动后自查并验证不空口附和文案一律 sentence case、句末带句号、正文不用 em/en dash、少用分号注释写意图而非复述代码Go 错误处理一律走cockroachdb/errors测试断言用testifyrequire只在无法继续执行时使用5xx 的错误日志留在 handler 内记录本地化只改locale_en-US.ini前端先做移动端再上桌面端任何 UI 都须达到 WCAG 2.2 AA需要服务端数据的页面一律在路由loader中取数前端模式遵循 web/DESIGN.md优先用moon run gogs:build、moon run web:dev等任务改完代码先跑对应lint并清零告警提交遵循 SSH 不直推main 不 amend worktree 目录名与分支名一致。这份文档的价值在于它把 Gogs 仓库多年沉淀的工程品味显式化为机器可读、可判罚的规则。无论你是人类贡献者还是 AI 编码助手遵循 AGENTS.md 都是在以仓库维护者认可的姿势推进改动从而让每一次提交都更接近一次通过。【免费下载链接】gogsThe painless way to host your own Git service项目地址: https://gitcode.com/GitHub_Trending/go/gogs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/8 20:21:47 · 阅读 1.2k Gogs 仓库的 AGENTS.md 工程协作规范全解读：从编码到提交的完整开发约定
Gogs 仓库的 AGENTS.md 工程协作规范全解读从编码到提交的完整开发约定【免费下载链接】gogsThe painless way to host your own Git service项目地址: https://gitcode.com/GitHub_Trending/go/gogs说明本文将基于 AGENTS.md 这份仓库级开发协作手册结合 Gogs自托管 Git 服务当前仓库的实际源码、构建配置与测试代码逐条解读其对 AI 开发助手与人类开发者提出的工作准则包括核心协作原则、Go 与前端编码规范、本地化流程、可访问性要求、构建与代码提交纪律。读者读完可以掌握在该仓库中高效协作的正确姿势以及每条规范背后的仓库实现依据。一、AGENTS.md 是什么给代码协作者的“行动总纲”在 Gogs 仓库根目录中AGENTS.md 是一份面向代码编写者尤其是 AI Agent的工程协作手册。它与普通的贡献指南不同内容高度浓缩条条都是可执行的硬性约束覆盖了从“接到任务后如何推进”到“写错代码时如何自纠”再到“文案、国际化、UI、提交”的全链路约定。该文件与仓库中其他文档如 web/DESIGN.md形成“总纲 细则”的关系AGENTS.md 负责定义适用于全仓库的通用规则并引用专门的模块文档作为补充约束。理解它等同于理解这个仓库当前被期望如何被维护。二、核心协作原则一次做对尊重现状文档开篇即强调两条贯穿始终的核心原则停止无意义的附和一次做对不要用“你说得对”这类空话回应而要在第一次尝试时就做正确并在改动后进行事实核查与自我复查如果不确定就主动求助。以当前版本为新的起点当发现超出自己知识范围的既有改动时不要盲目覆盖而是把它当作新起点尊重周边上下文中已经形成的模式。这两条原则的实际价值在于Gogs 是一个长期演进的成熟代码库覆盖cmd/、internal/下的 app、auth、context、database、route、repo 等大量子包以及web/前端工程任何机械化的“重写式”改动都极易破坏既有约定。文档明确要求 Agent 在改动前先以现有代码为锚点改动后先自查再交付这与仓库中大量配套测试例如 internal/database 下几乎每个模块都有同名_test.go的工程质量要求是一致的。三、Style and mechanics全仓库通用文案规则该规范适用于所有面向用户的文本包括但不限于 UI 文案、文档与代码注释。核心规则包括采用 sentence case句首大写、其余小写但品牌名保留原始大小写完整句子必须以句号结尾正文中禁止使用 em dash—与 en dash–应改写为逗号、句号、冒号或括号唯一的例外是作为 UI 设计中的视觉分隔符例如标题与描述之间不要过度使用分号两个短句通常比一个用分号连接的长句更清晰仅当两个子句耦合极强、拆分会丢失含义时才使用分号注释应解释代码无法直接表达的意图而不是复述代码行为优先使用更具描述性的命名。此规则优先于“跟随既有模式”CHANGELOG 条目只描述用户视角的可见影响不写入实现细节可对照仓库根目录的 CHANGELOG.md 的写作风格使用e.g.,与i.e.,时必须带尾随逗号。这些细节对中文社区团队同样有借鉴意义在提交信息、Release 说明与界面文案上保持一致的句式风格能显著降低多语言维护与后续机器翻译的成本。四、Coding guidelinesGo 侧的三条硬规范4.1 错误处理统一使用cockroachdb/errors文档规定所有 Go 代码的错误处理统一使用github.com/cockroachdb/errors。该要求与当前仓库的依赖声明完全一致go.mod 第 9 行声明了github.com/cockroachdb/errors v1.13.0。从源码看这一约定已被大面积落实。例如在 internal/database 的actions.go、attachment.go、comment.go、database.go、issue.go等实现中均大量使用errors.New、errors.Wrap系列调用为错误链保留原始上下文。选用该库的价值在于其丰富的堆栈信息保留能力便于在 Gogs 这类需要精确追踪数据库与 Git 操作失败原因的服务端代码中快速定位根因。4.2 测试断言统一使用stretchr/testify测试必须使用github.com/stretchr/testify进行断言同时要审慎选择require与assert当断言失败后测试无法继续有意义地执行时应当使用require立即终止反之才使用assert继续执行。该约定同样有仓库证据支撑go.mod 第 45 行声明github.com/stretchr/testify v1.11.1典型示例如 internal/database/access_tokens_test.go其中大量使用assert.Equal、assert.True、assert.False组合校验 token 的时间戳与使用状态字段。选择assert而非require的场景通常是同一实体多个字段的独立校验单点失败不影响其他断言继续执行反之若后续断言依赖前一步结果则应使用require尽早暴露问题。4.3 5xx 错误必须在 handler 内直接记录日志文档规定每一个 5xx 响应都必须在 handler 内部直接记录错误日志不要在共享 helper 中统一打日志。从源码结构看这正对应 internal/context/context.go 提供的Error、NotFoundOrError等上下文方法路由层在调用它们时同时传入人类可读的描述例如 internal/route/home.go 中的c.Error(err, search repository by name)从而让错误日志携带具体的业务语义而不是在底层共享封装里打出一堆无法区分场景的堆栈。这种“语义化日志下沉到调用点”的模式直接服务于 Gogs 生产环境下的问题定位效率。五、Localization本地化文件的“编辑主权”边界本地化是 Gogs 这类国际化项目的高频改动点文档给出了明确的权限边界只能编辑 conf/locale/locale_en-US.ini英文基准语言文件其他locale_*.ini由社区维护严禁增删或改写其中的键即使是删除 Go/模板侧已经失效的死键也不允许。仓库现状与该约定吻合conf/locale/目录下共存有 32 个语言文件含locale_zh-CN.ini、locale_ja-JP.ini、locale_ko-KR.ini等其中locale_en-US.ini是唯一由主仓库维护者直接掌管的基准源。这条规则的工程意义在于避免主分支与社区翻译仓库之间因键名不一致产生合并冲突保证自动化提取与回填流程可参考 web/scripts/extract-locales.mjs 这类脚本的同步基础永远以 en-US 为准。六、UI guidelines移动优先与无障碍底线前端工作必须遵守三条相辅相成的约束移动优先设计每个 UI 都必须在窄视口下先做好做对再通过响应式断点增加桌面端精化在约375px宽度下验证通过才能视为完成。至少满足 WCAG 2.2 AA具体量化要求包括每个交互控件都有可辨识的可访问名称可见 label 或aria-label颜色不能作为信息的唯一载体必须配文字、图标或形状正文与有意义图标相对背景满足4.5:1对比度大号文字与 UI 组件为3:1焦点始终可见且不会被困住触摸目标至少24×24 CSS px优先40×40。拿不准时宁可选择更高对比度、更大目标与更明确的标签。web/下的工作必须遵循 web/DESIGN.md中记录的排版、颜色层级、表面装饰、文件命名与无障碍细则当一个模式在两处被使用时就应当回写更新该文档。6.1 服务端数据的获取位置route loader 而非 useEffect文档对数据获取给出了一条非常具体的前端架构约束当页面需要服务端数据渲染时必须在 TanStack Router 路由的loader中获取让页面只在响应返回后才挂载严禁在页面组件内部用useEffect触发该请求否则会造成数据到达前先闪烁出空 UI。该约束在仓库中有清晰的实现对应web/src/router.tsx 基于 TanStack Router 构造路由树createRootRouteWithContext、createRoute并为根路由配置defaultErrorComponent: ServerError而 web/src/routes/repo.tsx 就是典型实践其路由节点定义了loaderDeps与异步loader在 loader 内完成请求并发起错误响应例如返回 404 而不浪费一次拉取。仓库中 web/src/pages/NotFound.tsx、web/src/pages/ServerError.tsx 等组件则承担路由错误渲染。七、Build instructions用 moon 统一构建与质量门禁当前仓库的前后端构建统一通过 moonrepoGo 后端项目 id 为gogs与 web/moon.ymlTypeScript 前端项目 id 为web定义了全套任务。文档要求尽量使用moon run project:task而不是裸的go/pnpm命令例如moon run gogs:build、moon run web:dev需要绕过缓存时传入--force改完 Go 代码后必须运行moon run gogs:lint改完前端代码后运行moon run web:lint并修复全部 linter 错误。两个 moon 配置文件中的关键任务对应关系整理如下任务后端moon.yml前端web/moon.yml安装依赖installgo mod tidygo generate ./...installpnpm install在工作区根执行格式化formatgolangci-lint fmtformatpnpm run formatLintlintgolangci-lint runlintpnpm run lint测试testgo test -cover -race ./...—构建buildgo build -v -trimpath并注入BuildTime/BuildCommit到.bin/gogsbuildpnpm run build输出到/public/dist开发运行servercd .bin ./gogs webdevpnpm run dev全量产物build-prod以-tags prod构建依赖web:build被后端build-prod依赖值得注意的实现细节build任务通过-ldflags -X gogs.io/gogs/internal/conf.BuildTime... -X ...BuildCommit...把编译时间与当前 commit 注入internal/conf包这意味着每次构建产物的版本信息都可在运行时追溯而build-prod会额外携带-tags prod并串联前端web:build构成前后端一致的生产构建链路。此外根 moon.yml 还提供了portless、dev、prod等组合任务用于把本地服务暴露到gogs.localhost开发域名。八、Tool-use guidance 与 Source code control工具纪律与提交纪律8.1 工具使用访问 GitHub 上非公开的信息时使用ghCLIChrome DevTools MCP 必须以 headless 模式运行避免抢走用户前台浏览器焦点任务结束后用pkill -f chrome-devtools-mcp清理所有残留进程。8.2 源码控制纪律从 fork 推送 PR 变更时使用 SSH 地址且不要添加 remote除非被明确要求绝不直接提交到main分支一次“允许”只对应 main 分支上的一次提交动作绝不擅自 amend 提交除非被明确要求创建 git worktree 时worktree 目录名必须与其分支名一致不得使用随机或生成的后缀。最后一条对多分支并行开发极具实操价值目录名 分支名的约定让本地多个 worktree 之间可以靠路径名直接辨别分支归属避免gogs-fix-a1k2这类无法识别的随机目录堆积。结合“不直推 main”“不 amend”两条纪律可以推断该仓库期望的协作流是功能分支或 fork 分支 → 提交 → PR 审查合并历史保持线性与可追溯。九、小结把规范变成可执行的协作清单将 AGENTS.md 的要点压缩为 AI 助手与贡献者的每日行动清单改动前先读周边代码以当前实现为起点改动后自查并验证不空口附和文案一律 sentence case、句末带句号、正文不用 em/en dash、少用分号注释写意图而非复述代码Go 错误处理一律走cockroachdb/errors测试断言用testifyrequire只在无法继续执行时使用5xx 的错误日志留在 handler 内记录本地化只改locale_en-US.ini前端先做移动端再上桌面端任何 UI 都须达到 WCAG 2.2 AA需要服务端数据的页面一律在路由loader中取数前端模式遵循 web/DESIGN.md优先用moon run gogs:build、moon run web:dev等任务改完代码先跑对应lint并清零告警提交遵循 SSH 不直推main 不 amend worktree 目录名与分支名一致。这份文档的价值在于它把 Gogs 仓库多年沉淀的工程品味显式化为机器可读、可判罚的规则。无论你是人类贡献者还是 AI 编码助手遵循 AGENTS.md 都是在以仓库维护者认可的姿势推进改动从而让每一次提交都更接近一次通过。【免费下载链接】gogsThe painless way to host your own Git service项目地址: https://gitcode.com/GitHub_Trending/go/gogs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考