2.8 KiB
Lessons Learned
Issue Management
Put everything in the issue body. Agents read the issue body; comments are unreliable. Add guidance by updating the body.
One decision per issue. Agents cannot choose between approaches. Decide before filing.
Explicit dependencies prevent ordering bugs. Use Depends-on: #N so agents don't work on stale code.
Fit issues to templates. Max 3 files, 5 acceptance criteria, clear solution. If it doesn't fit, it's too big—label vision and decompose.
Debugging CI Failures
Agents can't see CI logs. When an issue fails repeatedly, diagnose externally and put the exact error and fix in the issue body.
Blocked CI often means environment, not code. Missing libraries, auth failures, or path assumptions usually point to infrastructure misconfiguration.
Base Image and Environment
Minimal images introduce hidden traps. Alpine/musl libc breaks tools that work on glibc. Validate base image assumptions before committing to a path.
Ask: "What system libraries does this tool actually need?" Don't assume development environment constraints apply to production images.
Document base image tradeoffs. Alpine saves space but costs compatibility. Ubuntu saves compatibility but costs size. Make decisions explicit.
Authentication
Treat auth as first-class. Authentication assumptions are the most fragile part of any integration.
Audit all external calls. Map every operation touching remote systems and verify each has proper auth—even internal repos can require credentials.
Test in failure mode. Don't just verify the happy path. Simulate restricted access environments.
Verify the entire chain. Each layer in a call chain can strip credentials. Check every script, command, and library boundary.
Special cases often bypass standard flows. "Edge" or "beta" builds frequently have auth gaps.
Concurrency and Locking
Scope conditions to the actor, not the system. In multi-agent systems, distinguish "in progress" from "in progress by me."
Design blocking points with "who does this affect?" comments. Challenge any global-blocking condition: "What if five agents hit this simultaneously?"
State falls into three categories: global (affects all), actor-local, and shared resources. Only block on global state or own ownership.
Branch and PR Hygiene
Clean up stale branches before retrying. Old branches cause recovery mode with stale code. Close PR, delete branch, then relabel.
After a dependency lands, stale branches miss the fix. If issue B depends on A and B's PR predates A's merge, close and recreate the branch.
Feature Decomposition
Prefer gluecode over greenfield. Check existing APIs, libraries, or utilities before building new components.
Max 7 sub-issues per sprint. If more, split into two sprints.