parallel-agents

어떤 스킬인가요?

Coordinate edits when agents share a codebase, resolve shared-file conflicts, or address measured merge hotspots. Also use for maintaining AGENTS.md or CLAUDE.md. Do not impose file splits on ordinary solo changes.

설치 방법

프로젝트 폴더에서 아래 명령어를 실행하고, 설치할 에이전트를 선택하세요.

설치 명령을 직접 실행해야 적용됩니다. 지원 에이전트와 필요한 권한·라이선스는 제작자의 안내를 확인하세요.

스킬 원문 파일

interface:
  display_name: "Parallel Agents"
  short_description: "Structure and edit a codebase so parallel agents stop conflicting"
  default_prompt: "Use $parallel-agents to keep this change from colliding with parallel work."

# Doc gardening

Keep instructions useful to a fresh reader without duplicating the repository.
Reduce shared-doc churn when it causes conflicts; do not delete useful guidance
merely because a tool can rediscover it.

## What belongs where

AGENTS.md and CLAUDE.md hold working agreements, non-obvious constraints, and
concise entry points for setup and validation.

- Record intent and lessons that change an agent's decisions: why an obvious
  approach fails, an invariant, or a recurring failure.
- Keep the canonical setup and check commands easy to find. A short command
  remains useful even when it also appears in package scripts.
- Point to relevant module documentation rather than copying its detail.
- Avoid exhaustive file inventories, duplicated command help, and task status.

README and user guides explain concepts and common workflows. Keep enough
examples and commands for a reader to use the product without reconstructing
the intended procedure from source code.

## Decide what to keep

Ask whether the text saves meaningful discovery work or prevents a likely
mistake. Prefer a concise entry point or link when a maintained source already
contains the detail.

Do not reproduce full flag lists or directory trees that add no explanation.
Discoverability alone is not a reason to delete a setup step, test command,
or useful example.

## Prune within scope

Remove stale or duplicated guidance when maintaining the relevant document.
Remove a historical constraint when the underlying limitation is gone.
Do not delete progress files, plans, or user-maintained checklists merely
because they are not suitable for AGENTS.md.

Keep the root instructions stable. Put specialized guidance near the module
it governs, and update the root only when shared expectations or entry points
change.

# Hotspot audit

Conflicts concentrate where churn concentrates. This file covers finding the files
that attract every feature's edits and splits them so future work lands in
separate files. It is the retroactive companion to `one-feature-one-file.md`,
which prevents new hotspots from forming.

## Measure

Rank files by how many commits touched them over a recent window:

```sh
git log --since="3 months ago" --name-only --pretty=format: | grep -v '^$' | sort | uniq -c | sort -rn | head -25
```

Cross that against `wc -l`. The files to act on score high on both: churn
times size is a good single ranking. A small script beats eyeballing when the
repo is large.

## Diagnose before splitting

Not every hot file is a problem. Sort each candidate into one of three bins:

- **Hub**: touched by unrelated features. Read the last ten commits that
  touched it; if they share nothing except the file, it is a hub. Split it.
- **Hot concern**: touched often because that area is under active
  development. The churn is real work, not structure. Leave it alone.
- **Generated or lock file**: high churn is inherent. Splitting does not
  apply; handle these with `mergeable-edits.md` (regenerate, never
  hand-resolve).

Docs (AGENTS.md, README, design docs) are usually the top hotspots of all and
get their own treatment in `doc-gardening.md`.

## Split

- One file per concern. If the repo already has a split-by-concern directory
  (a module directory with `plan`, `runner`, `teardown` style siblings), copy
  that shape; consistency matters more than any particular layout.
- The split is a pure move: no behavior change, no symbol renames, no drive-by
  cleanup. The diff should be reviewable as "code moved, nothing else". Run
  the formatter and the full test suite; behavior must be identical.
- Update anything that points at the old layout: docs, architecture maps,
  paths in scripts and CI.

## Timing

A large move commit conflicts with every branch currently in flight, so a
split is a one-time conflict spike bought in exchange for a permanently lower
rate. Land it when the fleet is idle, or immediately rebase in-flight branches
after it lands. Do not interleave a split with feature work on the same files.

Note that plain `git log` on the new files starts at the move; `git log
--follow` recovers the prior history.

## Cadence

Re-run the measurement after a few weeks of fleet work. New hotspots form
wherever the structure still funnels unrelated growth into one file.

# Mergeable edits

Structure prevents most conflicts (see `one-feature-one-file.md`); this file
covers the shared files that legitimately remain: registration lines,
registries, config lists, and the generated files no structure can remove.
The goal is edits shaped so git's line-based merge resolves concurrent
branches on its own.

## Lists and registries

- One item per line, with a trailing comma or delimiter on every line, so
  adding an item is a strict one-line diff that touches no neighbor.
- Insert in a stable order, alphabetical unless the list is order-sensitive.
  Appending at the bottom makes every concurrent branch collide on the same
  last line; ordered inserts scatter across the file and merge cleanly.
- For a file that is genuinely an order-independent set of lines, a
  `.gitattributes` `merge=union` driver removes conflicts entirely. Use it
  sparingly: union merge never reports a conflict, so it is only safe where a
  duplicated or reordered line is harmless.

## Formatters and lint autofixers are exempt

Always run the repo's canonical formatter and lint autofixers. Their output
is deterministic, so branches that all run them converge to the same text
instead of conflicting; skipping them is what causes the formatting
conflicts. The ownership rules below govern discretionary edits, never
tool-enforced ones.

One scoping rule: if the formatter wants to change files your work never
touched, that is pre-existing drift, not part of your change. Format the
files you edited and leave the rest, or land the drift cleanup as its own
commit. Do not fold it into feature work.

## Do not own what you did not change

- Never hand-reflow paragraphs, reorder code, renumber lists, or apply style
  preferences the repo's tools do not enforce to regions your change does
  not touch. Every line you rewrite by choice is a line you now conflict on.
- Repo-wide sweeps (adopting a new formatter config, enabling a new lint
  rule and its autofix) go in their own commit, landed when no feature
  branches are in flight, never mixed into feature work.
- No drive-by fixes inside shared files. Note the issue and fix it in a
  separate change.

## Generated files and lockfiles

- Never hand-edit them, and never hand-resolve a conflict in them. Take
  either side wholesale, then regenerate with the owning tool (`templ
  generate`, `cargo build` for Cargo.lock, `go mod tidy`, the bundler for a
  compiled asset). The generator's output is the only correct content, and a
  hand-merged version is wrong in ways tests may not catch.
- If a generated file conflicts constantly, question whether it needs to be
  checked in at all; building it in CI may be the real fix.

## Resolving a conflict in a hub

When a conflict does land in a dispatcher or registry, resolve by intent:
both branches' one-line entries survive, placed in the file's stable order.
Then rerun the formatter and the tests. The classic parallel-agent bug is a
resolved registry with one branch's entry silently dropped; check for it
explicitly before committing.

# File boundaries for parallel work

Separate independently owned behavior when concurrent edits or observed
conflicts justify it. A file split should improve ownership or cohesion, not
satisfy a fixed line count.

## Recognize a shared-file hotspot

Look for unrelated work repeatedly touching the same dispatcher, registry,
router, stylesheet, test entry point, or root instruction file. File size alone
does not establish a conflict problem.

When a feature has a distinct owner, keep its body in a focused module and its
registration in the shared file. A small registration often merges cleanly,
but one line is a useful shape rather than a requirement.

## Choose a boundary

- CLI: a command handler can live separately from command registration.
- HTTP: group handlers by resource or behavior; keep routing concise.
- UI: keep page-specific components and styles near their page.
- Tests: follow the behavior's ownership. Add cases to an existing cohesive suite
  when that is clearer than creating another file.

Follow the project's layout. Do not split a small cohesive module or create
one-function files merely because parallel agents are available.

## Shared plumbing

Some changes need edits across a shared boundary. Keep them scoped and follow
[mergeable-edits.md](mergeable-edits.md) for generated files and conflict handling.
Propose an independent structural refactor rather than adding it to a bug fix
solely to prevent hypothetical future conflicts.

---
name: parallel-agents
description: Coordinate edits when agents share a codebase, resolve shared-file conflicts, or address measured merge hotspots. Also use for maintaining AGENTS.md or CLAUDE.md. Do not impose file splits on ordinary solo changes.
---

# Parallel agents

Keep independently owned work from colliding in shared files. Apply structural
changes when concurrent work or observed conflict history justifies them.

- Give independent behavior its own file when that creates a useful ownership
  boundary. Keep edits to shared registries small. Do not split a cohesive
  module merely to achieve a one-line registration.
- Shape shared lists for merging: one item per line, stable insertion order,
  and no unrelated reformatting. Regenerate generated files and lockfiles.
- Investigate repeated conflict hotspots before splitting them. Keep structural
  moves separate from behavior changes when both are requested.
- Keep agent docs concise: working agreements, non-obvious constraints, and
  useful setup/check entry points. Keep module detail near its owner.

## References

Read only the reference relevant to the task:

- [one-feature-one-file.md](references/one-feature-one-file.md): choosing file
  boundaries for concurrent feature work.
- [mergeable-edits.md](references/mergeable-edits.md): editing shared registries,
  generated files, or conflicting branches.
- [hotspot-audit.md](references/hotspot-audit.md): measuring conflict hotspots
  when an audit or structural repair is requested.
- [doc-gardening.md](references/doc-gardening.md): maintaining agent instructions
  or reducing duplicated documentation.