🛡️ AgentSeed

AI 코딩 에이전트를 위한 환각 방지 가드레일.

스펙 기반 개발을 강제하고 완료로 표시되기 전에 코드를 검증하는 하이브리드 Agent Plugins 플러그인(Skill + MCP Server)입니다. 따라서 "완료, 모든 테스트 통과"는 주장이 아니라 관측된 사실이 됩니다.

English · 中文 · 日本語

⭐ 이 프로젝트가 마음에 드시나요? 별을 남겨 주세요 — 개발자들이 환각 코드를 배포하기 전에 가드레일을 찾는 데 큰 도움이 됩니다.

왜 AgentSeed인가

LLM은 환각을 일으킵니다 — 코드의 경우 이는 존재하지 않는 API, 정의되지 않은 심볼, 가짜 테스트 통과, 그리고 장담하는 과장 주장을 뜻합니다. 수치로 보면:

• 코드 환각의 15.1% 는 지식과 충돌하는 유형입니다: 존재하지 않거나 임포트되지 않은 API를 호출합니다 (arXiv:2404.00971).

• 환각 코드의 <10%는 테스트에 실패합니다 — 나머지는 대부분 CI까지 통과합니다 (arXiv:2404.00971).

• 모델 출력 오류의 60%+ 는 검증 불가능합니다 — 헛... 사실과 허구를 구분할 방법이 없습니다 (FAVA, SoK에 인용).

프롬프트만으로 만든 가드레일은 연약합니다: 모델이 검증에 동의한 뒤 이를 건너뛸 수 있습니다. AgentSeed는 그 지시를 하드 MCP 게이트에 결합합니다 — 증거는 실행된 코드에서 나오지, 모델의 자체 보고에서 나오지 않습니다.

또한 1.0.0 스펙이 의도적으로 열어둔 두 가지 갭을 채웁니다:

Related MCP server: Metsuke

하는 일

여성 놈의 MCP 도구 — 전체 필수 의존성이 없고, 보조 도구로 향상:

시닫 합성 코퍼스 (5가지 결함 등급)에서 측정: 정밀도 1.0, 재현율 1.0 (tp=100, fp=0, fn=0) — 회귀 테스트가 이 수치를 고정합니다. 방법론과 정직한 적용 범위는 docs/BENCHMARK.md에 있습니다.

라이브 데모

$ verify_code(source="def f():\n    return magic_unknown()\n", language="python")
{
  "language": "python",
  "suspects": ["magic_unknown"]      # ← hallucinated API caught
}

$ scan_hallucination(source="The feature is production ready, all tests pass. Trust me.")
{
  "hits": [
    {"word": "all tests pass", "group": "oversold", "line": 1},
    {"word": "production ready", "group": "oversold", "line": 1},
    {"word": "trust me", "group": "oversold", "line": 1}
  ],
  "clean": false                      # ← overclaim caught
}

$ check_plugin(path="/path/to/AgentSeed")
{ "ok": true, "errors": [], "warnings": [] }   # ← strict 1.0.0 conformance

빠른 시작

옵션 A — 릴리스 내려받기 (git 없어 가능):

# grab the latest asset from https://gitcode.com/badhope/AgentSeed/releases
# or use the installer, which drops it into a client of your choice:
bash install.sh --client auto        # macOS / Linux
./install.ps1 -Client auto           # Windows PowerShell
# --client: claude | opencode | cursor | manual

옵션 B — 클론:

git clone https://gitcode.com/badhope/AgentSeed.git
# or: https://gitcode.com/badhope/AgentSeed · https://gitee.com/badhope/AgentSeed

1. Agent Plugin을 지원하는 클라이언트(Cursor, VS Code, Claude Code, Copilot…)에 AgentSeed/ 디렆터리를 옵어 넣습니다. 빌드/설치 불필요,전,제 필수·의존하지 않습니다 (선택 사항은 아래).

2. 클라이언트가 plugin.json + mcp.json에서 verify-before-code 스킬과 agentseed MCP 서버를 자동으로 발견합니다.

3. 끝입니다. 이 스킬은 이제 모든 코딩 작업을 게이트합니다: 계약 → 구현 → 검증 → 증거.

자체 점검으로 단독 실행해 보세요:

python3 server/guard_engine.py              # self-check: demo verify_code + scan_hallucination
python3 -m unittest discover -s server      # 90+ unit tests (also: `pytest` in CI)

동일 규칙으로 CI 모드에서 사람 PR을 게이트할 수도 있습니다:

python3 server/guard_cli.py gate --root .    # composite hard gate: conformance
                                             # + symbols + baseline scan, exit 1 on any failure
python3 server/guard_cli.py check . --ci     # plugin conformance only, exit 1 on errors
python3 server/guard_cli.py scan src/ --strict   # hallucination scan, blocking severities only

Windows 참고: mcp.json은 python3으로 서버를 구동합니다.·Windows에서 보통 저 별칭은 Microsoft Store 디-stub(stub)입니다.서버가 실패시 command에 ["python", "server/guard_server.py"]로 변경하거나 절대 경로 지정하십여.있는 Python 경로를 사용하세요.

선택적 의존성

AgentSEED는 Pythonㅍ양 라브러리만으로 동작합니다.선택 사한을 설치하면 개·도구가 업계ㅉ준 엔진으로 강되됩니다(어어울 자동 감지, 그에 맞가);:

pip install -r server/requirements.txt

guard_server.py의 절대 경로를 사용하세요나머지는 서버가 자기 위치에서 해결하므로 따로 cwd가 필요 없습니다.

호환성 및 우아한 성능 저하

AgentSeed는 호스트가 지원하는 만큼에 맞게 동작하며, 검증을 조용히 넘어가지 않고 한 단계씩 우아하게 저하합니다:

skill 자체에 강등 경로가 포함되어 있습니다. MCP 도구가 없으면, skill은 에이저에게 쉬 guard_cli.py verify/scan을 실행하도 하고 종료 코드에 동일한 차단 규칙을 적용하도 합니다.

플랫폼 지원

* 정직한 상태: 이 형식은 스ㄷ과 호환되며 작동할 것으로 만 뒤지만 self. AgentSeed를 이 클라이언트에서 직접 실행하지는 않았습니다. 검증 = 메인테이너가 실 답 동작을 확인했음을 뜻합니다. 하나라도 /작동을 확인한 경우 이 표를 갱신하는

⚠️ 보안 참고: sandbox_run은 실제 프로세스를 사용자 권한으로 실행합니다. 클라이언트는 사용자 승인 뒤에만 실행을 허용해야 하며, 공유/CI 환경에서는 sandbox_allowed_prefixes를 설정하세요. 허용목록이 구성되면 명령은 실행 전에 PATH를 통해 절대 경로로 해석됩니다 — 악의적인 작업 디렉터리가 허용된 베이스네임을 가른 심은 실행 파일로 위장할 수 없고, 일치하지 않거나 해석 불가능한 명령은 실행 없이 거부됩니다 (exit -10).

클라이언트 설정 — 정확한 구성

AgentSeed는 두 부분으로 구성됩니다. 전체 게이트를 위해서는 둘 다 필요합니다:

1. 스킬 (skills/verify-before-code/) — 에이전트에게 워크플로우를 가르칩니다.

2. MCP 서버 (server/guard_server.py) — 6가지 도구를 제공합니다.

설치 작업이 1단계를 연동하고 2단계를 클라이언트에 출력합니다. 수동 설정은 다음과 같습니다:

Claude Code

# skill: copy it flat so SKILL.md sits directly in the folder
cp -R skills/verify-before-code ~/.claude/skills/verify-before-code
# MCP server:
claude mcp add agentseed -- python /path/to/AgentSeed/server/guard_server.py

opencode — skills/verify-before-code/를 ~/.config/opencode/skill/verify-before-code로 복사한 뒤 opencode.json에 추가하세요:

{
  "mcp": {
    "agentseed": {
      "type": "local",
      "command": ["python", "/path/to/AgentSeed/server/guard_server.py"],
      "enabled": true
    }
  }
}

Cursor / 기타 MCP 클라이언트 — command: python, args: ["/path/to/AgentSeed/server/guard_server.py"]로 stdio 서버를 등록하고, 클라이언트의 스킬 위치에 맞춰 스킬 폴더를 복사하세요.

guard_server.py에 절대 경로를 사용하세요. 서버는 자체 위치를 기준으로 나머지 모든 것을 해석하므로 특별한 cwd가 필요하지 않습니다.

Changelog

CHANGELOG.md를 참조하세요.

기본 가드레일 라이브러리 (EN / 中文 / 日本語)

게이트의 동작 방식

1. 코딩 전 — SDD contract 목록을 로드하고 한 문장으로 언급한다.

2. 구현 — 실제 코드만 작성한다. 플레이홀더 없음, 존재하지 않는 API 쓰기 없음.

3. "완료"라고 하기 전 — verify_code + scan_hallucination을 호출하고, sandbox_run으로 런타임 주장을, schema_validate로 구조를 검증한다.

4. 언어 감사 — 완료 보고에는 근거 자료를 첨부하며, 과장 표현 어휘는 금지된다.

5. 모든 검사가 통과했을 경우에만 작업을 완료로 표시할 수 있는.

강제되는 규범 (AI가 어떻게 제한되다)

스킬은 동작을 단순 제안만 하지 않습니다. 각 규범은 준수를 테스트하는 게이트에 매핑됩니다:

이러한 규범은 강력한 에이전트 운영자들이 공개적으로 수렴한 것들과 동일한 것들을 종합한 것입니다 — AGENTS.md 오픈 표준, Anthropic의 Claude Code 모범 사례, 그리고 FerroxLabs/agents-md 같은 커뮤니티 규율(시각의 엔지니어 자세, 반-아첨, 강제 검증 루프) 등입니다. 차이점은 이렇습니다: 그 글에서는 권고(sub)에 불과하지만, 여기서는 모든 규범에 강제 도구 또는 종료 코드 존재합니다. 전체 표와 근거: skills/verify-before-code/references/DEFAULT-NORMS.md.

Agent 설정 파일과 함께 작동함

AgentSeed는 팀이 이미 AI 코딩 에이전트를 위해 관리하고 있는 컨텍스트 파일(CLAUDE.md, AGENTS.md, .cursor/rules/, .github/copilot-instructions.md, CONTRIBUTING.md)을 대체하는 것이 아니라 보완합니다:

• 그 파일들에는 성격: Stack, 명령어, 프로젝트 구조, 코딩 스타일 등 실제 사실이 .. 담고 있는데, 그냥 글이며 (권은 있지만) 준수 여부에 대한 강제는 없습니다.

• AgentSeed가 행동 인바운드와 적용(執行)을 담당: 환각 (hallucination) 감지, 검증 게이트, 근거 추적 — 하드 MCP 도구와 CI exit 코드로 되어 있어 조용히 우선 순위에서 밀려날 수 없습니다.

• 처리 대상마다 단일 정보 소스 유지: 이 스킬의 규범을 복사하지 말고 AGENTS.md가 이 규범을 가리키게 하세요. 플러그인이 업데이트되어도 규범은 계속 있어야 하는. 아니 계속 유지되며(속박됩니다).

왜 AgentSeed vs 대안들인가

로드맵

• Skill + MCP 하이브리드 가드레일, 도구 6개 — 처음으로 엄격한 1.0.0 린터

• 프롬프트 풀 + 패턴 라이브러리 + 그룹 신호 + 자율 도구

• TypeScript / JavaScript용 verify_code (의존성 제로 어휘 패스)

• Go용 verify_code

• 구조화 출력을 위한 문법 제한 디코딩

• 보조 원격 팩트 체커 (RHEM 스타일) MCP 서버

자주 묻는 질문

특정 LLM이 필요한가요? 아니요 — 클라이언트나 모델에 구애받지 않습니다. 게이트는 특정 모델이 아닌 스킬과 MCP 서버가 강제합니다.

Zero-dependency인가요? 맞습니다. MCP 서버 전체가 순수 Python 표준 라이브러리입니다.

Conformant한가요? check_plugin이 해당 플러그인을 규격(§5§6§7)에 대해 검증합니다 — 그리고 AgentSeed는 자기 자신의 린터를 통과합니다. (ok: true)

Protégé

이슈, PR, 아이디어는 언제나 환영합니다. 방향 여정은 로드맵 참고 또는, 아직 목록에 없는 환각 패턴을 발견하신 경우 문제 보고 이슈를 열어 주세요.

라이선스

Apache-2.0 © AgentSeed. LICENSE 참조.

지금까지 줄

⭐ AgentSeed가 당신의 환각 코드를 내보내지 않게 했다면 — 이 작은 신호는 가드레일이 작동하고 있다는 가장 강력한 영지이므로 별표를 눌러 주세요.