Notas prácticas: Domina Claude Code en Golang: 12 patrones para agencias
Guía paso a paso para utilizar las notas prácticas: Domina Claude Code en Golang: 12 patrones para sistemas agentes, incluyendo contratos, verificaciones y espacios de código reutilizable para equipos que implementan este patrón.
Úselo como una versión reestructurada dirigida a operadores de las ideas presentadas en “Master Claude Code in Golang: 12 Patterns for Agentic Developers”: etapas claras, secciones de código ordenadas y notas de recuperación que perduran tras la transferencia de tareas. La etapa de Resumen funciona mejor si se considera como una superficie medible. Capture una transcripción clave, un caso de fallo y la nota de reversión antes de ampliar el alcance. Prefiera unidades pequeñas y verificables en lugar de scripts extensos. Cuando un paso falla, el fallo debe apuntar a una única responsabilidad y no a un proceso complicado.
1. El prompt basado en la interfaz
En la fase 1 de Prompt basado en la interfaz, defina las entradas, el responsable de cada paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido sin tener que adivinar el estado oculto. Considere esta fase como un contrato entre las entradas y los resultados validados. Asigne nombres a los artefactos, defina verificaciones de éxito y rechace las completaciones parciales silenciosas. Prefiera resultados estructurados con validación de esquema sobre textos en formato libre cuando el siguiente paso sea escribir código o realizar una llamada a una herramienta.
# 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. Generación impulsada por pruebas (TDG)
Para la fase 2 de Generación Dirigida por Pruebas TDG, defina las entradas, el responsable de cada paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido sin tener que adivinar el estado oculto. Registre los tiempos de ejecución y el costo en tokens o consultas junto con los resultados funcionales. La visibilidad temprana de los costos evita facturas inesperadas cuando el proceso pasa de entornos de demostración a entornos compartidos. Implemente la aprobación humana en aquellos casos en los que se gastan fondos o se modifican datos de producción. La conexión en tiempo de compilación no equivale a la completitud del proceso empresarial.
# 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. Aplicación de restricciones contextuales mediante CLAUDE.md
Para la aplicación de control de contexto mediante etapas, defina las entradas, el responsable de cada paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido sin tener que adivinar el estado oculto. Mantenga la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de datos secretos y las banderas de funcionalidad deben estar en un lugar donde los operadores puedan auditarlos sin necesidad de leer todo el sistema. Coloque la aprobación humana en aquellos procesos que generan gastos o modifican datos de producción. La conexión establecida en tiempo de compilación no equivale a la completitud del proceso empresarial. Para la aplicación de control de contexto mediante etapas, defina las entradas, el responsable de cada paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido sin tener que adivinar el estado oculto. Prefiera unidades pequeñas y verificables en lugar de scripts extensos. Cuando un paso falla, el error debe indicar una única responsabilidad y no algo complicado.
pipeline.# 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. Envoltura explícita de errores
Al trabajar en la etapa de 4 Envolturas explícitas de errores, primero escribe el contrato: entradas requeridas, señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Trata esta etapa como un contrato entre las entradas y las salidas validadas. Nombra los artefactos, define las comprobaciones de éxito y rechaza la finalización parcial silenciosa. Haz una verificación después de los pasos costosos. La reanudación no debe volver a facturar la misma llamada al LLM cuando un operador intenta nuevamente un nodo posterior.
# 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. Estructuración de concurrencia
Al trabajar en la etapa 5 de estructuración para concurrencia, anote primero el contrato: las entradas requeridas, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Registre los tiempos y el costo de tokens o consultas junto con los resultados funcionales. Tener visibilidad del costo desde el principio evita facturas inesperadas cuando el proceso pasa de la demostración a entornos compartidos. Haga una verificación después de los pasos costosos. La reanudación no debe volver a facturar la misma llamada al LLM cuando un operador intenta nuevamente un nodo posterior.
# 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. Desarrollo orientado a tipos
Al trabajar en las 6 etapas del desarrollo orientado a tipos, anote primero el contrato: los datos de entrada requeridos, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación garantiza que los cambios posteriores en el código sean transparentes. Mantenga la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de datos secretos y las banderas de funcionalidad deben estar en un lugar donde los operadores puedan auditarlos sin tener que leer todo el sistema. Haga un punto de control después de los pasos costosos. La función de reanudación no debe volver a facturar la misma llamada al LLM cuando un operador intente nuevamente un nodo posterior. Al trabajar en las 6 etapas del desarrollo orientado a tipos, anote primero el contrato: los datos de entrada requeridos, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación garantiza que los cambios posteriores en el código sean transparentes. Prefiera unidades pequeñas y verificables a scripts extensos. Cuando un paso falla, el fallo debe referirse a una sola responsabilidad y no a un proceso complicado.
# 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. Directivas de Inyección de Dependencias
La etapa de las 7 Directivas de Inyección de Dependencias funciona mejor cuando se trata como una superficie medible. Capture una transcripción ejemplar, un caso de fallo y la nota de reversión antes de ampliar el alcance. Trate esta etapa como un contrato entre las entradas y las salidas validadas. Asigne nombres a los artefactos, defina verificaciones de éxito y rechace completaciones parciales silenciosas. Mantenga el estado del grafo plano y tipado. Los bloques anidados ocultan qué nodo escribió qué campo y provocan interrupciones en la continuación posterior.
# 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. Ajustes guiados por pruebas de rendimiento
La etapa de ajuste guiada por los 8 puntos de referencia funciona mejor cuando se trata como una superficie medible. Capture un transcripte ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Registre los tiempos y el costo en tokens o consultas junto con los resultados funcionales. Tener visibilidad del costo desde el principio evita facturas inesperadas cuando el proceso pasa de la fase de demostración a entornos compartidos. Mantenga el estado del gráfico simple y con tipos definidos. Los bloques anidados ocultan qué nodo escribió qué campo y provocan interrupciones en la continuación del proceso.
# 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. Etiquetado estructurado iterativo
La etapa de etiquetado estructurado iterativo 9 funciona mejor cuando se trata como una superficie medible. Capture un registro ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Mantenga la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de secretos y las banderas de funcionalidad deben estar en un lugar donde los operadores puedan auditarlos sin tener que leer todo el grafo. Mantenga el estado del grafo plano y tipado. Los bloques anidados ocultan qué nodo escribió qué campo y causan interrupciones en la continuación del proceso. La etapa de etiquetado estructurado iterativo 9 funciona mejor cuando se trata como una superficie medible. Capture un registro ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Prefiera unidades pequeñas y probables sobre scripts extensos. Cuando un paso falla, el fallo debe apuntar a una sola responsabilidad en lugar de a un proceso complicado.
# 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. Sugerencias idiomáticas con GoDoc
En la fase 10 de inducción idiomática con GoDoc, defina las entradas, el responsable de cada paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido, sin tener que adivinar el estado oculto. Considere esta fase como un contrato entre las entradas y los resultados validados. Asigne nombres a los artefactos, defina verificaciones de éxito y rechace las completaciones parciales silenciosas. Prefiera resultados estructurados con validación de esquema sobre textos en formato libre cuando el siguiente paso sea la generación de código o una llamada a una herramienta.
# 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. El bucle de errores de compilación agente
En la etapa 11 de Error de Compilación por Agente, defina las entradas, el responsable del paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido sin tener que adivinar el estado oculto. Registre los tiempos de ejecución y el costo en tokens o consultas junto con los resultados funcionales. La visibilidad temprana de los costos evita facturas inesperadas cuando el proceso pasa de entornos de demostración a entornos compartidos. Implemente la aprobación humana en aquellos casos en que se gasten fondos o se modifiquen datos de producción. La configuración en tiempo de compilación no equivale a la completitud del proceso empresarial.
# 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. Aplicación de Límites Arquitectónicos (Modo Plan)
En la fase 12 de Aplicación de Límites Arquitectónicos, defina las entradas, el responsable de la tarea y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar la tarea desde un punto de control conocido sin tener que adivinar el estado oculto. Mantenga la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de datos secretos y las banderas de funcionalidad deben estar en un lugar donde los operadores puedan auditarlos sin necesidad de leer todo el sistema. Coloque la aprobación humana en las operaciones que generan gastos o modifican datos de producción. La conexión realizada en tiempo de compilación no equivale a la completitud del proceso empresarial. En la fase 12 de Aplicación de Límites Arquitectónicos, defina las entradas, el responsable de la tarea y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar la tarea desde un punto de control conocido sin tener que adivinar el estado oculto. Prefiera unidades pequeñas y verificables en lugar de scripts extensos. Cuando una tarea falla, el error debe indicar a un único responsable.
mejor que un pipeline enredado.# 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
}
Bueno, entonces, ¿en qué patrón confías más al trabajar con IA? Deja un comentario abajo y hablemos de cómo evoluciona esta tecnología de agentes tan innovadora.
Al pasar por la fase de determinar el patrón a seguir, escribe primero el contrato: entradas requeridas, señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones en el código. Considera esta fase como un contrato entre las entradas y los resultados validados. Nombra los artefactos, define las verificaciones de éxito y rechaza las completaciones parciales silenciosas. Haz un punto de control después de los pasos costosos. La función de reanudación no debe volver a facturar la misma llamada al LLM cuando un operador intenta nuevamente un nodo posterior.
Lista de verificación operativa
Al trabajar en la fase de lista de verificación operativa, anote primero el contrato: los datos necesarios, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código.
Documente tanto el camino óptimo como el de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son ajustes realizados posteriormente.
Haga una verificación después de los pasos costosos. La función de reanudación no debe volver a facturar la misma llamada al LLM cuando un operador vuelve a intentar un nodo posterior.
Fije las versiones de las dependencias y registre el resumen de la imagen que ejecutó la demostración. La reproducibilidad es mejor que el conocimiento basado en prácticas internas.
Prefiera unidades pequeñas y verificables en lugar de scripts extensos. Cuando un paso falla, el fallo debe apuntar a una única responsabilidad y no a un proceso complicado.
Haga una verificación después de los pasos costosos. La función de reanudación no debe volver a facturar la misma llamada al LLM cuando un operador vuelve a intentar un nodo posterior.
Antes de promocionar el conjunto de herramientas, congele las versiones, capture una transcripción de referencia para la ruta crítica y confirme los pasos para revertir cambios. Los entornos compartidos requieren límites de velocidad, verificaciones de tenencia y un responsable claro para la rotación de credenciales secretas. Prefiera una fiabilidad sólida a demostraciones ingeniosas pero puntuales.
Nota para el lote 09e9b0c0b1cd: mantenga las claves del proveedor fuera del repositorio, establezca un límite para tokens por sesión y almacene las transcripciones junto a los archivos de prueba para que los cambios en los modelos posteriores sigan siendo comparables.
Lecturas relacionadas
- Notas prácticas: Mejores prácticas de Claude Code: 12 patrones que utilizan los ingenieros agentic — Guía detallada de las Notas prácticas: Mejores prácticas de Claude Code: 12 patrones que utilizan los ingenieros agentic, incluyendo contratos, verificaciones y espacios para código reutilizable para equipos que implementan este patrón.