Project Structure & .env Management: Building Robust ADK Go Projects

一个人在写代码怎么乱都行，团队协作就不一样了。这篇文章讲的是如何组织一个规范的 ADK Go 项目，让团队成员clone下来就能跑，API Key 不泄露，代码结构清晰。

一个人写代码怎么乱都行，团队协作就不一样了。这篇文章讲的是如何组织一个规范的 ADK Go 项目，让团队成员clone下来就能跑，API Key 不泄露，代码结构清晰。

A person writing code can be messy, but team collaboration is different. This article covers how to organize a standard ADK Go project so team members can clone and run it immediately, API Keys don’t leak, and code structure is clear.

A Standard ADK Go Project Structure

my_agent/
├── agent.go              # Main entry file
├── .env                  # API Key and sensitive config (not committed)
├── .env.example          # Environment variable template (committed)
├── .gitignore
├── go.mod
├── go.sum
└── README.md

It’s that simple. ADK Go project structure itself isn’t complex, core is just one agent.go. But “not complex” doesn’t mean “anything goes”—good structure and standards make later maintenance and team collaboration much smoother.

go.mod: Module Initialization

Each ADK Go project is a Go Module. First step is to initialize go.mod:

cd my_agent
go mod init my-agent/main

This generates go.mod file, content roughly like this:

module my-agent/main

go 1.24.4

require (
    google.golang.org/adk v0.2.0
    google.golang.org/genai v0.3.0
)

Then run:

go mod tidy

This command auto-downloads dependencies based on import statements and generates go.sum. Run go mod tidy every time after adding new dependencies.

.env and .env.example: Sensitive Info Separation

This is one of the most important standards.

Principle: .env has real values but not committed to git; .env.example has sample values for others’ reference.

.env.example Template

export GOOGLE_API_KEY="your-api-key-here"
export MODEL_NAME="gemini-flash-latest"
export LOG_LEVEL="info"

Team members copy project, copy .env.example to .env and fill in their own values:

cp .env.example .env

.gitignore Configuration

# Environment
.env
.env.local
.env.production
.env.*.local

# Dependencies
go.sum

# IDE
.idea/
.vscode/
*.swp

# OS
.DS_Store
Thumbs.db

# Build
bin/
dist/

Key point: Write go.sum to .gitignore—because dependency version lock info can be regenerated from go.mod, team members run go mod tidy to stay in sync.

Multi-Environment Config: Development / Staging / Production

Projects with team collaboration usually have multiple environments. Simplest way to distinguish via .env files:

my_agent/
├── .env                 # Developer local (not committed)
├── .env.example         # Shared template
├── .env.staging         # Staging environment
├── .env.production      # Production environment (managed via CI/CD, not committed to repo)

Switch environment locally:

source .env.staging  # Load staging environment variables
go run agent.go

Or pass via command-line arguments:

func main() {
    env := "development"
    if len(os.Args) > 1 {
        env = os.Args[1]
    }
    // Load different configs based on env
}

README.md: Let Team Members Get Started Quickly

A standard project README contains:

Project description
Prerequisites (Go version, ADK Go version)
Installation steps
Running steps
Environment variable instructions
Directory structure description

Example:

# My ADK Go Agent

An assistant Agent built with Google ADK Go.

## Prerequisites

- Go 1.24.4+
- ADK Go v0.2.0+
- Google API Key

## Quick Start

1. Clone project
2. Copy environment variable template: `cp .env.example .env`, fill in real values
3. Install dependencies: `go mod tidy`
4. Run: `source .env && go run agent.go`

## Environment Variables

| Variable | Description | Required |
|----------|-------------|----------|
| GOOGLE_API_KEY | Google Gemini API Key | Yes |
| MODEL_NAME | Model name, default gemini-flash-latest | No |

Team Collaboration Standards

Branch Strategy

main          # Stable version
├── develop   # Development branch
├── feat/*    # Feature branches
└── fix/*     # Fix branches

Commit Standards

feat: Add weather query Agent
fix: Fix API Key not loaded issue
docs: Update README
chore: Upgrade ADK Go to v0.2.1

Code Review

Before each merge to develop branch, at least one team member Code Review.

Common Issues

Q: .env accidentally committed to git, what to do? A: Immediately delete from git history and change passwords:

git filter-branch --force --index-filter \
  'git rm --cached --ignore-unmatch .env' \
  --prune-empty --tag-name-filter cat -- --all

Also confirm .env added in .gitignore.

Q: Team members have different GOPROXY configs, causing go mod tidy results inconsistent A: Agree on using same proxy, add one line at top of go.mod:

// 约定使用 goproxy.cn

Q: Multiple Agent projects need to share some basic tools, how to organize? A: Build internal tool package:

internal/
└── tools/
    ├── weather.go
    └── search.go

Then use replace directive in go.mod pointing to local path:

replace google.golang.org/adk => ../internal/adk

Next Steps

With project structure standards established, move to Module 2: Quick Start. Start with Agent’s core concepts, understand the three elements: Model, Tool, Instruction.

← ADK Go Installation & Quick Verification | Agent Core Concepts →

Follow “Mengshou Programming” on WeChat for more Go ADK hands-on tutorials, weekly updates on Go / AI programming 实战干货.

Project Structure & .env Management: Building Robust ADK Go Projects#

A Standard ADK Go Project Structure#

go.mod: Module Initialization#

.env and .env.example: Sensitive Info Separation#

.env.example Template#

.gitignore Configuration#

Multi-Environment Config: Development / Staging / Production#

README.md: Let Team Members Get Started Quickly#

Team Collaboration Standards#

Branch Strategy#

Commit Standards#

Code Review#

Common Issues#

Next Steps#