ワンクリックでManusで任意のスキルを実行

project-adapters

スター3

フォーク3

更新日2026年6月24日 15:20

Step-by-step workflow for adding, modifying, or debugging a source-format adapter. Use whenever editing an adapter under internal/adapters, internal/canonical, or related fixture files.

インストール

Codex または Claude でインストールこの Prompt をコピーして Codex、Claude、または他のアシスタントに貼り付けると、Skill ページを確認してインストールできます。

Manusで実行

ソース

netdata

netdata/ai-viewer

GitHub リポジトリを開く Creator のリポジトリを見る

ダウンロード

Manusで実行

Adapters

Mental Model

An adapter is a sealed unit that converts one source format into the canonical event stream. It knows everything about its format and nothing about anything else. See .agents/sow/specs/adapter-contract.md.

Adding a New Adapter

Read the format authoritatively first. Open the upstream source mirror under /opt/baddisk/monitoring/repos/ai/<tool>/ and read its persistence code. Sample real files (sanitized) from the operator's environment.
Write the spec first. Create .agents/sow/specs/adapter-<name>.md. Required sections: source format, record shape, watch strategy, cursor design, mapping to canonical events, sub-agent linkage, known edge cases, references. The spec is the source of truth; the code follows.
Create the package. internal/adapters/<name>/adapter.go. Implement the canonical.Adapter interface. Keep the file under 400 lines; split helpers into sibling files.
Commit sanitized fixtures. testdata/<name>/<scenario>/. Scenarios are listed in testing-strategy.md. Run scripts/sanitize-fixture.sh before committing.
Write tests. Scan, Tail, cursor resume, error handling, idempotency. Use golden files.
Register the factory. internal/adapters/registry.go:
```
registry["myadapter"] = myadapter.Factory
```
Add auto-discovery probe. internal/ingest/discover.go: add a probe entry that detects the format's presence on disk.
Update docs. README.md Source Formats table; docs/adding-an-adapter.md if any new patterns emerged.
Open or update a SOW. Use the external reviewer gates from project-second-opinions on the adapter SOW's gap analysis, implementation plan, and implementation before closing the work.

Modifying an Existing Adapter

Read the adapter's spec under .agents/sow/specs/adapter-<name>.md.
Read recent commits to that adapter (git log -p internal/adapters/<name>/).
Check existing fixtures for coverage of the case you're touching.
Make the change.
Update the spec in the same commit as the code.
Run go test ./internal/adapters/<name>/... with -race.
If the canonical mapping changed, refresh golden files with -update-golden and inspect the diff manually before committing.

Common Pitfalls

Closing the out channel. Don't. The ingester owns it.
Panicking on bad input. Don't. Call opts.OnError and continue.
Re-emitting on every Scan call. Use the cursor; the ingester does dedup but adapter-side dedup is far cheaper.
Forgetting to Add new subdirs. fsnotify in Go is not recursive; you must Add each subdirectory.
Reading symlinks outside the configured root. Resolve with filepath.EvalSymlinks and verify the result is inside the root.
Holding files open across goroutine boundaries. Open, read, close in one goroutine.

Cursor Design Tips

A cursor must be persistable and resumable. Don't store live channels or file handles.
Idempotent on replay: scanning twice with the same cursor should produce the same events.
Survive source rewrites: if the source overwrites a file, the cursor must detect it (mtime + size + content hash where appropriate).

Sub-Agent Linkage

The canonical model expresses sub-agents as SessionStartedEvent with ParentNativeID set. The adapter is responsible for figuring out parent/child relationships from the source format and emitting that field correctly. The ingester does the cross-session resolution; the adapter just provides the native IDs.

Validation Checklist

Before marking adapter work complete:

Spec under .agents/sow/specs/adapter-<name>.md matches the implementation.
Fixtures cover happy/multi-turn/sub-agents/tools/failures/in-progress/cursor-resume.
Golden files reviewed manually.
go test -race ./internal/adapters/<name>/... passes.
golangci-lint run ./internal/adapters/<name>/... clean.
Auto-discovery probe added.
README Source Formats table updated.
Applicable external reviewer gates from project-second-opinions converged for the adapter SOW or substantial milestone.

このリポジトリの他の Skills

同じリポジトリ

project-coding

netdata/ai-viewer

Apply ai-viewer coding standards for production-quality Go and TypeScript changes. Use for implementation, refactoring, runtime behavior changes, and any change where clean code, separation of concerns, modularity, or maintainability matters.

2026-07-113

project-go-backend

netdata/ai-viewer

Apply Go-specific patterns used in ai-viewer for fsnotify watching, SQLite access, SSE streaming, and structured logging. Use when editing internal/ingest, internal/store, internal/presenter, internal/adapters, internal/canonical, or internal/obs.

2026-06-303

project-second-opinions

netdata/ai-viewer

Run ai-viewer's external reviewer gates. Use on meaningful chunks of work, at least per SOW and per substantial SOW milestone: gap analysis, implementation plan, and implementation review. Reviewers are glm, minimax, kimi, mimo, deepseek, and qwen. They are gates, not implementers.

2026-06-303

project-workflow

netdata/ai-viewer

Master orchestration cycle for ai-viewer work — gap→plan→spec→test→code→gates→review→commit. The CTO writes implementation directly. Helper subagents are optional for bounded investigation, not the implementation norm. External reviewers are three milestone gates per meaningful feature, substantial batch, or SOW, not routine delegation.

2026-06-303

project-quality-gates

netdata/ai-viewer

Catalog of every automated quality gate ai-viewer enforces — commands, thresholds, and what to do when a gate fails. Use before claiming any work done, before any commit, when adding a new gate, or when investigating a CI failure. The runtime companion to .agents/sow/specs/quality-gates.md.

2026-06-283

project-specs-sync

netdata/ai-viewer

Keep ai-viewer specs synchronized with code. Use whenever a code change touches runtime behavior, defaults, schemas, contracts, file layouts, or external interfaces.

2026-06-283

Adapters

Mental Model

Adding a New Adapter

Read the format authoritatively first. Open the upstream source mirror under /opt/baddisk/monitoring/repos/ai/<tool>/ and read its persistence code. Sample real files (sanitized) from the operator's environment.

Write the spec first. Create .agents/sow/specs/adapter-<name>.md. Required sections: source format, record shape, watch strategy, cursor design, mapping to canonical events, sub-agent linkage, known edge cases, references. The spec is the source of truth; the code follows.

Create the package. internal/adapters/<name>/adapter.go. Implement the canonical.Adapter interface. Keep the file under 400 lines; split helpers into sibling files.

Commit sanitized fixtures. testdata/<name>/<scenario>/. Scenarios are listed in testing-strategy.md. Run scripts/sanitize-fixture.sh before committing.

Write tests. Scan, Tail, cursor resume, error handling, idempotency. Use golden files.

Register the factory. internal/adapters/registry.go:

registry["myadapter"] = myadapter.Factory

Add auto-discovery probe. internal/ingest/discover.go: add a probe entry that detects the format's presence on disk.

Update docs. README.md Source Formats table; docs/adding-an-adapter.md if any new patterns emerged.

Open or update a SOW. Use the external reviewer gates from project-second-opinions on the adapter SOW's gap analysis, implementation plan, and implementation before closing the work.

Modifying an Existing Adapter

Read the adapter's spec under .agents/sow/specs/adapter-<name>.md.

Read recent commits to that adapter (git log -p internal/adapters/<name>/).

Check existing fixtures for coverage of the case you're touching.

Make the change.

Update the spec in the same commit as the code.

Run go test ./internal/adapters/<name>/... with -race.

If the canonical mapping changed, refresh golden files with -update-golden and inspect the diff manually before committing.

Common Pitfalls

Closing the out channel. Don't. The ingester owns it.

Panicking on bad input. Don't. Call opts.OnError and continue.

Re-emitting on every Scan call. Use the cursor; the ingester does dedup but adapter-side dedup is far cheaper.

Forgetting to Add new subdirs. fsnotify in Go is not recursive; you must Add each subdirectory.

Reading symlinks outside the configured root. Resolve with filepath.EvalSymlinks and verify the result is inside the root.

Holding files open across goroutine boundaries. Open, read, close in one goroutine.

Cursor Design Tips

A cursor must be persistable and resumable. Don't store live channels or file handles.

Idempotent on replay: scanning twice with the same cursor should produce the same events.

Survive source rewrites: if the source overwrites a file, the cursor must detect it (mtime + size + content hash where appropriate).

Sub-Agent Linkage

Validation Checklist

Before marking adapter work complete:

Spec under .agents/sow/specs/adapter-<name>.md matches the implementation.

Fixtures cover happy/multi-turn/sub-agents/tools/failures/in-progress/cursor-resume.

Golden files reviewed manually.

go test -race ./internal/adapters/<name>/... passes.

golangci-lint run ./internal/adapters/<name>/... clean.

Auto-discovery probe added.

README Source Formats table updated.

Applicable external reviewer gates from project-second-opinions converged for the adapter SOW or substantial milestone.

name	project-adapters
description	Step-by-step workflow for adding, modifying, or debugging a source-format adapter. Use whenever editing an adapter under internal/adapters, internal/canonical, or related fixture files.