docs: improve agent contribution guidance

[liangshuo-1]

Summary

Rework the root AGENTS.md into concise, project-specific guidance that helps coding agents choose the correct implementation owner, preserve CLI contracts, and validate changes without mistaking environment failures for product bugs.

Changes

• Add the project's implementation discipline, including YAGNI, root-cause ownership, and the command/shortcut/internal/extension/affordance/skill routing table.
• Document non-obvious build prerequisites and generated metadata behavior, plus the real FileIO/vfs/os, output, and structured-error boundaries.
• Clarify affordance and skill progressive disclosure, E2E expectations, diff-scoped quality-gate limitations, and maintenance criteria for future root rules.

Test Plan

• git diff --check origin/main...HEAD
• Verified referenced files, Markdown anchors, Make targets, and named Go symbols.
• Scanned the final document for credentials, tokens, private network data, internal domains, local user paths, and sensitive test data; no matches.
• Unit tests pass — not run because this is a documentation-only change and canonical test targets first fetch remote metadata.
• Manual local lark-cli <domain> <command> verification — not applicable; runtime behavior is unchanged.

Related Issues

• None

Summary by CodeRabbit

• Documentation
  • Reworked project guidance for implementation practices, build prerequisites, testing, validation, and documentation maintenance.
  • Added guidance for API and file handling, structured errors, output behavior, generated metadata, end-to-end coverage, and CI checks.
  • Refined commit quality and isolated testing requirements to support more reliable contributions.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: cd25d74f-3cb1-4fe6-96b0-771e5610dbf6

📥 Commits

Reviewing files that changed from the base of the PR and between bd7dd91 and b76845a.

📒 Files selected for processing (1)

• AGENTS.md

🚧 Files skipped from review as they are similar to previous changes (1)

• AGENTS.md

---

📝 Walkthrough

Walkthrough

AGENTS.md was rewritten with rules for implementation discipline, build prerequisites, surface selection, hard contracts, structured errors, affordances, skills, testing, validation, CI checks, maintenance, and contribution requirements.

Changes

Repository guidance

Layer / File(s)	Summary
Implementation foundations AGENTS.md	Adds rules for implementation discipline, contract tracing, reuse, build prerequisites, offline behavior, and implementation-surface selection.
Contracts and structured errors AGENTS.md	Defines requirements for output streams, errors, Cobra wiring, runtime APIs, filesystem access, interfaces, typed errors, and error metadata tests.
Testing, validation, and maintenance AGENTS.md	Adds behavioral and end-to-end testing requirements, deterministic test setup, validation and CI checks, test-binary warnings, documentation maintenance, and contribution requirements.

Estimated code review effort: 2 (Simple) | ~10 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the documentation update to agent contribution guidance.
Description check	✅ Passed	The description includes all required sections and explains the documentation scope and validation results.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/optimize-agents-md

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 4

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@AGENTS.md`:
- Around line 46-60: Update the Build section in AGENTS.md to state that `go
build .` uses the tracked `internal/registry/meta_data_default.json` stub when
`scripts/fetch_meta.py` is not run, while the fetch script provides the full
metadata catalog. Remove the reference to `internal/registry/meta_data.json`
from the later prerequisite guidance, without changing the build commands or
product code.
- Around line 79-111: Fix the JSON output contract reference in the Hard
Contracts section of AGENTS.md by pointing it to an existing README section
anchor, or add the missing JSON output contract anchor to README.md before
retaining the link. Ensure the link resolves to the actual contract
documentation.
- Around line 129-145: Add a reachable-content test that reads shipped
documentation through the embedded content path, registering embeddedContentFS
via cmd.SetEmbeddedSkillContent and/or cmd.SetEmbeddedAffordanceContent, or
exercising the real skills read/docs flow in tests/plugin_e2e/skills_test.go.
Ensure the test fails when content_embed.go lists a path that is missing or
unreadable from the embedded filesystem, while preserving the existing
missing/partial embed coverage.
- Around line 195-205: Update the Go PR validation instructions near the pinned
go run checks to state that Go must be able to download uncached modules through
the configured module proxy, or document an equivalent offline/cache setup
before running them. Keep the existing pinned commands unchanged.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: d7b4efae-059a-4ad8-8b36-0452ff32e359

📥 Commits

Reviewing files that changed from the base of the PR and between 2016120 and bd7dd91.

📒 Files selected for processing (1)

• AGENTS.md

[github-actions]

🚀 PR Preview Install Guide

🧰 CLI update

npm i -g https://pkg.pr.new/larksuite/cli/@larksuite/cli@b76845a85b348593a605c090931dd9e633e74167

🧩 Skill update

npx skills add larksuite/cli#docs/optimize-agents-md -y -g

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 76.36%. Comparing base (2016120) to head (b76845a).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #2259   +/-   ##
=======================================
  Coverage   76.36%   76.36%           
=======================================
  Files        1011     1011           
  Lines      111269   111269           
=======================================
  Hits        84970    84970           
  Misses      19815    19815           
  Partials     6484     6484           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.