|
| 1 | +# AGENTS.md |
| 2 | + |
| 3 | +This file provides guidance to LLM/AI coding agents working with this repository. It is agent‑agnostic and compatible with commonly used agents (e.g., Claude Code, Gemini CLI, Codex CLI, Cursor, Warp, Cline). |
| 4 | + |
| 5 | +## 1. Purpose |
| 6 | + |
| 7 | +Concise, actionable rules for agents to work safely and effectively in this repo. |
| 8 | + |
| 9 | +## 2. Environment & Workspace |
| 10 | + |
| 11 | +- Node.js v22.12.0+ (do not downgrade) |
| 12 | +- Package manager: pnpm workspaces |
| 13 | +- Run all commands from the repository root |
| 14 | + |
| 15 | +## 3. Agent Workflow |
| 16 | + |
| 17 | +- Setup |
| 18 | + - `corepack enable` |
| 19 | + - `pnpm install` |
| 20 | +- Validate |
| 21 | + - `pnpm type-check` |
| 22 | + - `pnpm test` |
| 23 | + - `pnpm lint` |
| 24 | +- Build (when needed) |
| 25 | + - `pnpm -r build` |
| 26 | + - `pnpm --filter <package> build` |
| 27 | +- Prefer non‑interactive, pager‑free, and safe operations. |
| 28 | +- For package-specific commands and examples, refer to each package's README (e.g., `packages/release-tracking/README.md`, `packages/batch-pr/README.md`). |
| 29 | + |
| 30 | +## 4. Code Style Essentials |
| 31 | + |
| 32 | +- Prefer arrow functions for business logic; exceptions include class methods, constructors, generators, or intentional hoisting. |
| 33 | + |
| 34 | +```ts path=null start=null |
| 35 | +// Preferred |
| 36 | +export const parseLines = (text?: string): string[] => { |
| 37 | + const t = text?.trim(); |
| 38 | + if (!t) return []; |
| 39 | + return t.split(' |
| 40 | +').filter(line => line.trim() !== ''); |
| 41 | +}; |
| 42 | + |
| 43 | +// Acceptable when hoisting is necessary |
| 44 | +export function bootstrap(config: Config): void { |
| 45 | + // ... |
| 46 | +} |
| 47 | +``` |
| 48 | + |
| 49 | +- Organize modules with public API near the top and implementation details at the bottom. |
| 50 | + |
| 51 | +```ts path=null start=null |
| 52 | +// 1) Imports |
| 53 | + |
| 54 | +// 2) Public types/constants |
| 55 | +export type SyncResult = { created: number; updated: number }; |
| 56 | + |
| 57 | +// 3) Public API (high-level orchestration) |
| 58 | +export const syncCommits = async (cfg: Config): Promise<SyncResult> => { |
| 59 | + const commits = await getCommits(cfg); |
| 60 | + const filtered = filterCommits(commits, cfg); |
| 61 | + return applyChanges(filtered, cfg); |
| 62 | +}; |
| 63 | + |
| 64 | +// 4) Private implementation details (bottom) |
| 65 | +const getCommits = async (cfg: Config) => { |
| 66 | + /* ... */ |
| 67 | +}; |
| 68 | +const filterCommits = (commits: Commit[], cfg: Config) => { |
| 69 | + /* ... */ |
| 70 | +}; |
| 71 | +const applyChanges = (commits: Commit[], cfg: Config): SyncResult => { |
| 72 | + /* ... */ |
| 73 | +}; |
| 74 | +``` |
| 75 | + |
| 76 | +- Readability via blank lines: use exactly one blank line to separate logical blocks. Avoid multiple consecutive blank lines. |
| 77 | +- Formatting and imports: Prettier governs formatting and import grouping/sorting. Keep imports stable; avoid deep relative imports across package boundaries. |
| 78 | +- Logging and errors: use `utils/log.ts` (log types: I, S, W, E). Info/success logs gated by `VERBOSE=true`. Avoid raw `console.*`. Throw `Error` with actionable messages. |
| 79 | + |
| 80 | +## 5. Repo Layout |
| 81 | + |
| 82 | +- Monorepo using pnpm workspaces |
| 83 | +- TypeScript with project references; Vitest (V8 coverage); GitHub Actions; shelljs with silent output |
| 84 | +- Repository layout: |
| 85 | + |
| 86 | +```text path=null start=null |
| 87 | +packages/ |
| 88 | +├── core/ # Execution engine & @yuki-no/plugin-sdk exports |
| 89 | +│ ├── infra/ # Git/GitHub integrations |
| 90 | +│ ├── plugin/ # Plugin loader + SDK bindings |
| 91 | +│ ├── types/ # Shared TypeScript definitions |
| 92 | +│ ├── utils/ # Common utilities (logging, filters) |
| 93 | +│ ├── utils-infra/ # Infra utilities (issue creation, commit tracking) |
| 94 | +│ └── index.ts # Main entry point |
| 95 | +├── release-tracking/ # Official plugin for release status tracking |
| 96 | +└── batch-pr/ # Official plugin for batch PR creation |
| 97 | +``` |
| 98 | + |
| 99 | +- High-level architecture (summary): key files include |
| 100 | + - Config: `packages/core/createConfig.ts` |
| 101 | + - Git: `packages/core/infra/git.ts` |
| 102 | + - GitHub: `packages/core/infra/github.ts` |
| 103 | + - Orchestration: `packages/core/index.ts` |
| 104 | + |
| 105 | +## 6. API Boundaries & Compatibility |
| 106 | + |
| 107 | +- Public surface (SDK): `@yuki-no/plugin-sdk` from `packages/core`. |
| 108 | +- Public exports are defined in `packages/core/package.json` (exports map); treat these as the supported contract (`infra/_`, `utils/_`, `utils-infra/_`, `types/_`). |
| 109 | +- Avoid importing non-exported internals; prefer exported entry points only. |
| 110 | +- SemVer: breaking SDK changes require a major version bump. Official plugins pin the SDK via `peerDependencies` (e.g., `^1.x`). |
| 111 | + |
| 112 | +## 7. Plugin Authoring Pointers |
| 113 | + |
| 114 | +- A plugin must default-export an object with a name and optional hooks. |
| 115 | +- Refer to `packages/core/types/plugin.ts` for the canonical hooks, order, and contracts. Do not duplicate those details here. |
| 116 | +- Use the provided `ctx.config`; avoid side effects outside hook boundaries. |
| 117 | +- When specifying plugins in workflows/actions, pin explicit versions (e.g., `@yuki-no/plugin-release-tracking@1.0.0`). |
| 118 | + |
| 119 | +## 8. Tooling Usage & Safety |
| 120 | + |
| 121 | +When a task involves file I/O, project-wide code edits, multi-step planning, up-to-date docs, or web research, use MCP in this order (and state which tool you used): |
| 122 | + |
| 123 | +1. filesystem — reading/writing/searching files |
| 124 | +2. serena — semantic code navigation and safe edits |
| 125 | +3. context7 — latest, version-specific docs/examples |
| 126 | +4. tavily — real-time web search/extract/crawl |
| 127 | +5. sequential — explicit step-by-step planning or reflection |
| 128 | + |
| 129 | +If the chosen MCP call is unavailable or errors, briefly note it and continue with non‑MCP methods to avoid blocking. |
| 130 | + |
| 131 | +Safety and approvals |
| 132 | + |
| 133 | +- Do not run interactive or long‑running commands; avoid pagers; prefer safe, non‑destructive operations. |
| 134 | +- Preserve user‑owned changes; never overwrite without explicit instruction. |
| 135 | +- Handle secrets via environment variables only; never print secrets. |
| 136 | +- If the repository state is unexpected or a change seems risky or irreversible, stop and request guidance. |
| 137 | + |
| 138 | +## 9. Quick Checklist |
| 139 | + |
| 140 | +- Node 22 + pnpm; run from the repo root |
| 141 | +- Install → type‑check → test → lint → (optional) build |
| 142 | +- Use MCP in the order above; keep outputs concise; show exact diffs or commands for changes |
| 143 | +- Make minimal, focused changes; verify with tests |
| 144 | + |
| 145 | +## 10. Maintaining This Guide |
| 146 | + |
| 147 | +Update when any of the following change: |
| 148 | + |
| 149 | +- Node.js engine requirement or package manager |
| 150 | +- Monorepo layout (packages added/removed/renamed) or TypeScript project references |
| 151 | +- Public exports of `@yuki-no/plugin-sdk` or plugin lifecycle/type contracts |
| 152 | +- Repo-wide commands (type-check, test, lint, build) or their recommended usage |
| 153 | +- MCP servers that are installed/configured and their preferred usage order |
| 154 | + |
| 155 | +Keep guidance concise; avoid duplicating workflow/automation details here; ensure examples compile and naming matches the current codebase. |
0 commit comments