docs

Imported from hieudoanm/hieudoanm.github.io (packages/app/headless/cv/languages/go/docs/AGENTS.md). Install upstream with npx skills add hieudoanm/hieudoanm.github.io --skill docs. Copyright stays with the author.

🤖 Agents

Entry point for coding agents in this repo. This file is the router, not the rulebook. It holds only the conventions that hold across every language, and points at the directories that hold everything else.

Indexes: .agents/TREE.md · .skills/TREE.md Run python3 .agents/scripts/validate.py to check agent metadata, local links, workflow routes, and the agent tree.

How to work here

1. Adopt a persona — it fixes identity, priorities, boundaries and the quality bar.
2. Follow a workflow — it fixes the phases and the Definition of Done for the change type.
3. Consult the matching skill — it owns the stack's conventions, idioms and pitfalls.
4. Ground it in reality — read examples/ and the surrounding code before inventing a pattern.

Never restate a convention that a skill already owns. If a rule is missing from a skill, add it to the skill instead of duplicating it here. This file stays under 200 lines for the same reason code does: a rule an agent has to hunt for is a rule it will not apply.

Before a change, inspect relevant guidance, implementation, documentation, and tests. Afterward, validate the change and review the diff. Report the outcome, material trade-offs, validation, and unresolved issues when relevant. For significant decisions, check constraints and prior decisions, consider a reasonable alternative, and prefer the simplest solution that meets the requirements.

📐 Coding Convention

Language-agnostic. Stack-specific rules live in .skills/.

1. Explicit types > Implicit — TypeScript types, Rust annotations, Python hints, Kotlin signatures. A signature tells more than a hundred lines of body.
2. Flat over deeply nested — Shallow trees, short functions, minimal indentation. Callback hell and 5-level if pyramids exhaust a context window faster than anything else.
3. Self-documenting identifiers — getUserById(id) needs no comment; processData(x) needs one. Name the what and the why, never the how.
4. Don't repeat yourself — When a pattern appears 15 times across files, an agent will handle 14 of them and miss the 15th. Centralise it.
5. Small, focused files — One responsibility per file. Functions ≤ 30 lines, because an agent's reasoning degrades past ~2000 tokens and a 30-line function stays visible next to its callers. Files ≤ 200 lines — beyond that, tracing data flow between distant sections becomes guesswork. If you have to scroll to see a whole function, it is too long.
6. Explicit error handling — if (err) return Err(...) rather than silent propagation. Agents must see the error path to handle it.
7. Test names as documentation — test("returns 404 when user not found") reads faster than the implementation.
8. Consistent import structure — Group by origin: stdlib, third-party, internal. Agents infer the dependency graph from import blocks alone.
9. Prefer pure functions with explicit dependencies — Take inputs as parameters, return outputs; no globals or singletons. Return values are the single source of truth; mutations hide their impact.
10. Conventional project layouts — src/, cmd/, internal/, tests/. Agents locate files by convention instead of scanning build configs.

🔀 Stack → skill

Open the playbook before writing code in a stack. Never carry conventions between stacks by memory.

Skills follow one shape: name/description frontmatter, numbered sections, bolded rules, then a Quick-Start Checklist. Match that shape when you add one. Several skills are written against a specific major version — read the intro before trusting an example.

🔄 SDLC

📦 Workspace

A pnpm workspace (packages/**) driven by turbo. pnpm-workspace.yaml also pins allowBuilds for native modules and overrides for transitive deps — change those, not the lockfile.

Commands (turbo fans these out across the workspace; test is serialised to avoid port clashes):

pnpm dev          # watch mode          pnpm lint        # lint
pnpm build        # production build    pnpm typecheck   # types only
pnpm test         # full test suite     pnpm format      # write

🧪 Examples

examples/ holds runnable multi-file artifacts, not snippets — the things a skill cannot inline. Prefer a skill snippet for a pattern; prefer examples/ when you need a whole file to copy or a stack to actually run.

When you add one, keep the path shape and link it from the relevant skill. When you find a skill whose "quick start" should really be a working stack, add the artifact rather than growing the playbook — playbooks are capped at 200 lines for a reason.

✅ Definition of Done

• Persona adopted, workflow followed, its DoD met
• Matching skills consulted; no convention invented against them
• Functions ≤ 30 lines, files ≤ 200 lines
• Error paths explicit and tested
• pnpm lint, pnpm typecheck, pnpm test green
• No secrets; no unrelated churn in the diff
• Any missing convention added to the right skill, not to this file

This is NOT the Turborepo you know

Turborepo configuration, task behavior, and CLI commands can vary between installed versions and may differ from your training data. Resolve the turbo package from this file's directory or relevant workspace; in monorepos, it may not be visible from the repository root. For example, run node -p "require.resolve('turbo/package.json')" from a workspace that depends on turbo.

Read docs/README.md inside that installed package first, then read the relevant pages from its docs/ directory before changing Turborepo configuration or commands. Heed deprecation notices. These bundled docs match the installed package version and are available without network access.

This block is written and re-added by turbo before repository-scoped commands when an AI agent is detected. In the Turborepo source repository, its template is defined in crates/turborepo-cli/src/cli/agent_guidance.rs. Removing the managed block while updates are enabled means a later qualifying invocation will add it again. Set "agentGuidance": false in the root turbo.json or turbo.jsonc to opt out; this does not remove an existing block. Keep the block committed with your work to avoid an uncommitted change on the next agent invocation.