Практические заметки: Освойте Claude Code на Golang: 12 шаблонов для агентного программирования

Используйте это как переработанную версию идей из книги «Овладейте кодом Claude на Golang: 12 шаблонов для разработчиков-агентов» в формате, предназначенном для операторов: четкие этапы, упорядоченные блоки кода и записи о восстановлении, сохраняющиеся при передаче задач. Этап Обзора работает наилучшим образом, если рассматриваться как измеримая основа. Соберите один идеальный пример выполнения, один случай сбоя и запись о возврате к предыдущему состоянию перед расширением объема работ. Предпочитайте небольшие, проверяемые единицы кода большим скриптам. Когда какой-либо шаг срывается, причина сбоя должна указывать на конкретную ответственность, а не на запутанную цепочку операций.

1. Запрос с упором на интерфейс

На этапе 1 «Интерфейс во главе» необходимо определить входные данные, ответственного за выполнение шага и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Рассматривайте этот этап как контракт между входными данными и проверенными выходными результатами. Укажите названия элементов, определите критерии успеха и не допускайте молчаливого частичного выполнения задачи. При следующем шаге, представляющем собой код или вызов инструмента, отдавайте предпочтение структурированным выходным данным с проверкой по шаблону перед свободным текстовым форматом.

# Terminal Command:
claude "Implement the PaymentGateway interface using Stripe in stripe.go. Ensure all methods return mapped domain errors, not raw stripe errors."

// Go Interface Contract:
type PaymentGateway interface {
    Charge(ctx context.Context, amount int64) (string, error)
    Refund(ctx context.Context, transactionID string) error
}

2. Генерация на основе тестов (TDG)

На втором этапе тест-ориентированного генерирования TDG необходимо заранее определить входные данные, ответственного за выполнение шага и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Рядом с функциональными результатами следует записывать время выполнения и стоимость токенов или запросов. Отображение затрат на раннем этапе предотвращает неожиданные счета при переходе с демо-среды в общедоступные среды. Людское утверждение должно применяться к операциям, связанным с расходами или изменением производственных данных. Настройка на этапе компиляции не гарантирует полноты решения с точки зрения бизнес-требований.

# Terminal Command:
claude "Run `go test -v ./calc` and implement calculator.go to make these exact tests pass without changing the test assertions."

// Go Test File:
func TestCalculateDiscount(t *testing.T) {
    result := CalculateDiscount(100, "VIP")
    if result != 80 {
        t.Errorf("Expected 80, got %d", result)
    }
}

3. Обеспечение соблюдения контекста с помощью CLAUDE.md

Для реализации контроля контекста по этапам необходимо заранее определить входные данные, ответственного за шаг и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Храните конфигурацию вне кода приложения. Файлы среды, хранилища секретов и флаги функций должны находиться в одном месте, которое операторы могут проверять, не читая весь код. Вводите человеческое утверждение для операций, связанных с тратой денег или изменением производственных данных. Подключение компонентов во время компиляции не гарантирует полноты бизнес-логики. Для реализации контроля контекста по этапам необходимо заранее определить входные данные, ответственного за шаг и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Предпочитайте небольшие, тестируемые единицы кода вместо обширных скриптов. При сбое шага он должен указывать на конкретную причину, а не на сложную совокупность факторов.

пайплайн.

# Excerpt from CLAUDE.md:
## Go Conventions
Rule: Every exported I/O or database method MUST accept `context.Context` as its first parameter and pass it to the underlying driver (e.g., using `QueryRowContext`).

4. Явное обертывание ошибок

При работе над этим этапом явного обертывания ошибок сначала запишите условия работы: необходимые входные данные, сигнал о успехе и то, что происходит при частичной неудаче. Такой чек-лист поможет сохранять честность при последующих изменениях кода. Рассматривайте этот этап как контракт между входными данными и проверенными выходными данными. Дайте названия результатам обработки, определите критерии успеха и не допускайте безусловного частичного завершения работы. Выполняйте контрольные точки после ресурсоемких шагов. Механизм возобновления работы не должен повторно оплачивать один и тот же вызов большой языковой модели, когда оператор пытается выполнить следующий узел.

# Terminal Command:
claude "Refactor config.go. If os.Open fails, wrap the error with context using fmt.Errorf and the %w verb."

// Generated Go Code:
file, err := os.Open("config.json")
if err != nil {
    return fmt.Errorf("failed to open config file: %w", err)
}

5. Основы конкурентности

При работе над этапом 5 «Основы конкурентности» сначала запишите контракт: необходимые входные данные, сигнал о успешном выполнении и действия при частичной неудаче. Такой чек-лист помогает сохранять честность при последующих изменениях кода. Рядом с функциональными результатами занесите информацию о времени выполнения и стоимости токенов или запросов. Отображение затрат с самого начала предотвращает неожиданные счета при переходе от демо-среды к общедоступным средам. Выполняйте контрольные точки после дорогостоящих шагов. Функция возобновления работы не должна снова взимать плату за один и тот же вызов большой языковой модели, когда оператор пытается выполнить более поздний узел.

# Terminal Command:
claude "Implement a worker pool for the Job slice in worker.go. Use a buffered channel of size 5 and a sync.WaitGroup. Ensure the WaitGroup is closed cleanly."

// Go Code Scaffold:
jobs := make(chan Job, 5)
var wg sync.WaitGroup
// Claude generates the exact worker loop here based on the constraints

6. Разработка, ориентированная на типы

При работе над 6 этапами разработки, основанной на типах, сначала запишите контракт: необходимые входные данные, сигнал успешного выполнения и действия при частичной неудаче. Такой список помогает сохранять честность последующих изменений в коде. Храните конфигурацию отдельно от кода приложения. Файлы среды, хранилища секретов и флаги функций должны находиться в одном месте, чтобы операторы могли их проверять, не читая весь код. Создавайте контрольные точки после дорогостоящих шагов. Система возобновления работы не должна снова взимать плату за один и тот же вызов большой языковой модели, когда оператор пытается выполнить более поздний этап. При работе над 6 этапами разработки, основанной на типах, сначала запишите контракт: необходимые входные данные, сигнал успешного выполнения и действия при частичной неудаче. Такой список помогает сохранять честность последующих изменений в коде. Предпочитайте небольшие, тестируемые единицы кода большим скриптам. При сбое шага причина неудачи должна указывать на конкретную ответственность, а не на запутанную структуру обработки данных.

# Terminal Command:
claude "Refactor the User struct. Change all string IDs to a custom type UserID string, and ensure all functions accepting an ID use this new type."

// Generated Go Code:
type UserID string
type User struct {
    ID    UserID
    Email string
}

7. Директивы внедрения зависимостей

Этот этап 7 директив внедрения зависимостей работает наилучшим образом, если рассматривать его как измеримую поверхность. Зафиксируйте один идеальный пример работы, один случай сбоя и записку о возврате к предыдущему состоянию перед расширением объёма работ. Рассматривайте этот этап как контракт между входными данными и проверенными выходными результатами. Дайте названия элементам, определите критерии успешности и не допускайте молчаливого частичного выполнения задачи. Сохраняйте структуру графа простой и типизированной. Вложенные структуры данных скрывают информацию о том, какой узел заполнил тот или иной поле, что приводит к нарушению возобновления работы после перерывов.

# Terminal Command:
claude "Rewrite NewOrderService. Do not initialize the logger inside. Pass a *zap.Logger and a PaymentGateway interface as dependencies."

// Generated Go Code:
func NewOrderService(logger *zap.Logger, gateway PaymentGateway) *OrderService {
    return &OrderService{
        logger:  logger,
        gateway: gateway,
    }
}

8. ⏱ Оптимизация на основе тестов производительности

Этап настройки, основанный на 8 показателях критериев оценки, работает наилучшим образом, если рассматриваться как измеримая поверхность. Сначала соберите один идеальный пример работы, один случай сбоя и запись о возврате к предыдущему состоянию, прежде чем расширять объем работ. Записывайте временные показатели, а также стоимость токенов или запросов рядом с функциональными результатами. Отображение стоимости на ранних этапах предотвращает неожиданные счета при переходе от демо-среды к общедоступным средам. Сохраняйте структуру графа простой и типизированной; вложенные структуры скрывают информацию о том, какой узел заполнил тот или иной поле, и могут нарушить возобновление работы после прерываний.

# Terminal command piping benchmark results directly to Claude Code:
go test -bench . -benchmem | claude "Our allocs/op is too high in the parser. Rewrite the parse function to use a sync.Pool for the byte slices."

// Generated Go Code:
var bufferPool = sync.Pool{
    New: func() any {
        b := make([]byte, 1024)
        return &b
    },
}

9. Итеративная маркировка структур

Этап 9 итеративной структурированной маркировки работает наилучшим образом, когда рассматривается как измеримая поверхность. Соберите один идеальный пример записи, один случай сбоя и записку о возврате к предыдущему состоянию перед расширением объёма работы. Храните конфигурацию вне кода приложения. Файлы среды, хранилища секретов и флаги функций должны находиться в одном месте, чтобы операторы могли их проверять, не читая весь граф. Сохраняйте состояние графа простым и типизированным. Вложенные структуры скрывают информацию о том, какой узел записал какое поле, и мешают возобновлению работы после прерываний. Этап 9 итеративной структурированной маркировки работает наилучшим образом, когда рассматривается как измеримая поверхность. Соберите один идеальный пример записи, один случай сбоя и записку о возврате к предыдущему состоянию перед расширением объёма работы. Предпочитайте небольшие, тестируемые единицы кода вместо обширных скриптов. Когда какой-то шаг сбивается, причина сбоя должна указывать на конкретную ответственность, а не на запутанную цепочку операций.

# Terminal Command:
claude "Create a Go struct from this JSON payload. Add `json` tags, and include `validate` tags ensuring the email is valid and the age is >= 18."

// Generated Go Code:
type RegistrationRequest struct {
    Email string `json:"email" validate:"required,email"`
    Age   int    `json:"age" validate:"gte=18"`
}

10. Идиоматичное использование GoDoc для получения подсказок

На этапе 10 «Идиоматическое формулирование запросов в GoDoc» необходимо заранее определить входные данные, ответственного за выполнение шага и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг, исходя из известной точки контроля, без необходимости угадывать скрытое состояние. Рассматривайте этот этап как контракт между входными данными и проверенными результатами. Дайте названия результатам работы, определите критерии успеха и не допускайте молчаливого частичного завершения задачи. При следующем шаге, представляющем собой написание кода или вызов инструмента, предпочтительнее использовать структурированные результаты с проверкой по шаблону вместо свободного текста.

# Terminal Command:
claude "Add GoDoc comments to all exported types and functions in user_repo.go. Start the comment with the name of the identifier."

// Generated Go Code:
// UserRepository handles database operations for the User entity.
type UserRepository struct {
    db *sql.DB
}

11. Цикл ошибок компиляции агента

На этапе 11 «Ошибка компиляции агентного кода» необходимо заранее определить входные данные, ответственного за выполнение шага и критерии завершения перед внесением изменений в код. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии системы. Рядом с функциональными результатами следует записывать время выполнения и стоимость токенов или запросов. Отображение затрат на раннем этапе предотвращает неожиданные счета при переходе от демо-среды к общедоступным средам. Людское утверждение должно применяться к операциям, связанным с расходованием средств или изменением производственных данных. Настройка на этапе компиляции не гарантирует полноты решения с точки зрения бизнес-требований.

# Terminal Command:
claude "Run `go build ./...`. If it fails with type conversion errors, fix the casts in handler.go and retry until it compiles cleanly."

// Claude correctly casts the primitive to the custom type to fix the build:
userID := UserID(user.ID)
err := repo.GetByID(ctx, userID)

12. Обеспечение соблюдения архитектурных границ (режим планирования)

На этапе 12 «Обеспечение соблюдения архитектурных границ» необходимо определить входные данные, ответственного за выполнение шага и критерии завершения перед внесением изменений в код. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Храните конфигурацию вне кода приложения. Файлы среды, хранилища секретов и флаги функций должны находиться в одном месте, которое операторы могут проверять, не читая весь код. Вводите утверждение человека для операций, связанных с тратой денег или изменением производственных данных. Подключение компонентов во время компиляции не гарантирует полноты бизнес-логики. На этапе 12 «Обеспечение соблюдения архитектурных границ» необходимо определить входные данные, ответственного за выполнение шага и критерии завершения перед внесением изменений в код. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Предпочитайте небольшие, тестируемые единицы кода большим скриптам. При сбое шага он должен указывать на конкретного ответственного.

вместо запутанной системы обработки.

# Terminal Command:
claude "Create a new Order handler. Rule: Do not import the 'database/sql' package in this file. You may only interact with the database via the OrderUseCase interface. Use plan mode to show me the approach first."

// Generated Go Code:
func (h *OrderHandler) Create(w http.ResponseWriter, r *http.Request) {
    // Claude generates clean HTTP handling without leaking DB logic here
}

Итак, на какой шаблон вы в большей степени полагаетесь при работе с ИИ? Оставьте комментарий ниже, и давайте обсудим, как развивается эта сумасшедшая технология агентов!

На этапе определения шаблона сначала запишите контракт: необходимые входные данные, сигнал успешного выполнения и что происходит при частичной неудаче. Такой список помогает сохранять честность при последующих изменениях кода. Рассматривайте этот этап как контракт между входными данными и проверенными выходными результатами. Укажите названия элементов, определите критерии успеха и не допускайте безответственного частичного выполнения задач. Создавайте контрольные точки после дорогостоящих операций. Система возобновления работы не должна повторно запрашивать один и тот же вызов LLM, когда оператор пытается выполнить следующий этап.

Чек-лист для операционной работы

При работе над этапом операционного чек-листа сначала запишите условия контракта: необходимые входные данные, сигнал успешного выполнения и действия при частичной неудаче. Такой чек-лист помогает сохранять честность при последующих изменениях кода.

Задокументируйте одновременно успешный сценарий работы и сценарий восстановления. Повторные попытки, проверки со стороны оператора и обработка ошибок являются частью продукта, а не элементами последующей доработки.

Создавайте контрольные точки после дорогостоящих шагов. Система возобновления работы не должна снова взимать плату за один и тот же вызов LLM при повторной попытке оператора обработки последующего узла.

Фиксируйте версии зависимостей и записывайте хэш изображения, использованного для демонстрации. Воспроизводимость важнее коллективных знаний.

Предпочитайте небольшие, тестируемые модули большим скриптам. При сбое какого-либо шага причина неудачи должна указывать на конкретную ответственность, а не на запутанную цепочку операций.

Создавайте контрольные точки после дорогостоящих шагов. Система возобновления работы не должна снова взимать плату за один и тот же вызов LLM при повторной попытке оператора обработки последующего узла.

Перед внедрением стека заморозьте версии, сделайте копию «золотого» транскрипта для критической цепочки операций и уточните шаги возврата к предыдущему состоянию. В совместных средах необходимы ограничения на частоту запросов, проверки принадлежности пользователя и четко определенный ответственный за обновление секретов. Лучше выбирать надежность, чем креативные одноразовые демонстрации.

Примечание для 09e9b0c0b1cd: не храните ключи поставщика в репозитории, установите лимит токенов на сессию и сохраняйте транскрипты рядом с фиксами для оценки, чтобы последующие замены моделей оставались сопоставимыми.