Практичні нотатки: Опануйте Claude Code у Golang: 12 шаблонів для агентних систем
Покрокове керівництво з практичних нотаток: Опануйте Claude Code у Golang: 12 шаблонів для агентних систем – контракти, перевірки та готові блоки коду для команд, які використовують ці шаблони.
Використовуйте цей документ як оновлену версію ідей з книги „Master Claude Code in Golang: 12 Patterns for Agentic Developers“, орієнтовану на операторів: чіткі етапи, впорядковані блоки коду та примітки щодо відновлення, які залишаються при передачі обов’язків. Етап Огляду найкраще функціонує, якщо його розглядати як вимірювану основу. Запишіть один ідеальний запис, один випадок збою та примітки щодо скасування змін перед розширенням обсягу роботи. Віддавайте перевагу невеликим, тестованим одиницям коду перед об’ємними скриптами. Коли якийсь крок зазнає невдачі, причина має вказувати на конкретну відповідальність, а не на заплутану послідовність операцій.
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)
Для другого етапу Test-Driven Generation 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. Чітке обгортання помилок
Під час роботи над 4 етапами чіткого обгортання помилок спочатку запишіть умови використання: необхідні вхідні дані, сигнал про успіх та те, що відбувається у разі часткової невдачі. Цей перелік допомагає зберігати чесність у подальших змінах коду. Розглядайте цей етап як угоду між вхідними даними та перевіреними результатами. Дайте назви елементам, визначте критерії успіху та не допускайте беззвучного часткового виконання. Робіть перевірки після дорогих кроків. Функція відновлення не повинна знову оплачувати той самий виклик LLM, коли оператор перезапускає пізнішу ланку.
# 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 етапів створення інфраструктури для конкурентності спочатку запишіть контракт: необхідні вхідні дані, сигнал про успіх та те, що відбувається у разі часткової невдачі. Такий перелік допомагає зберігати чесність пізніших змін у коді. Запишіть час виконання та витрати на токени або запити поруч із функціональними результатами. Відображення витрат на ранньому етапі запобігає несподіваним рахункам, коли процес переходить від демо-середовища до спільних. Робіть контрольні пункти після дорогих кроків. Система повторного запуску не повинна знову стягувати плату за один і той самий виклик LLM, коли оператор перезапускає пізніший етап.
# 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 етапами розробки, керованої типами, спочатку запишіть контракт: необхідні вхідні дані, сигнал про успіх та те, що відбувається при частковій невдачі. Цей перелік допомагає зберігати чесність подальших змін у коді. Тримайте конфігурацію окремо від коду додатку. Файли середовища, сховища секретних даних та флаги функцій мають знаходитися в одному місці, де оператори можуть їх перевіряти, не читаючи весь код. Робіть контрольні пункти після дорогих кроків. Система відновлення не повинна знову стягувати плату за один і той самий виклик LLM, коли оператор перезапускає пізніший етап. Під час праці над 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 «The Agentic Compile-Error» необхідно визначити вхідні дані, власника кроку та критерії завершення перед зміною коду. Оператори повинні мати можливість перезапустити крок з відомої точки контролю, не намагаючись визначити прихований стан. Записуйте час виконання та витрати на токени або запити поруч із функціональними результатами. Чітке бачення витрат заздалегідь запобігає несподіваним рахункам під час переходу з демо-середовища у спільні. Встановіть людське схвалення для кроків, які витрачають гроші або змінюють дані в продакшені. Підключення під час компіляції не є гарантією повноти бізнес-функціоналу.
# 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, коли оператор намагається знову виконати пізніший етап.
Перш ніж запускати стек у продакшн, заморозьте версії, створіть «золотий» запис для критичного шляху та підтвердьте кроки для скасування змін. У спільних середовищах необхідні обмеження на частоту використання, перевірки прав доступу та чіткий власник для зміни секретів. Віддавайте перевагу надійності перед креативними одноразовими демонстраціями.
Примітка до 09e9b0c0b1cd: не включайте ключі постачальника до репозиторію, встановіть ліміт токенів на сеанс та зберігайте записи поруч із фіксами для оцінки, щоб подальша заміна моделей залишалася порівнянною.