CI
License: MIT
Python 3.11+
AI 에이전트 툴킷 for 1C:Enterprise 8.3 (BSL) 개발. MIT. 문서는 러시아어로 되어 있습니다.
**1С:Предприятие 8.3 (BSL)**에서 AI 에이전트를 사용하여 개발하기 위한 규칙, 스킬 및 MCP 서버 모음입니다. 이 에이전트는 사용자의 구성(configuration)과 확장(extensions)의 코드를 검색하고, 수정할 때마다 BSL Language Server 진단을 받아 메타데이터(폼, СКД, 속성)를 테스트 데이터베이스에서 검증하는 결정론적 엔진으로 변경합니다. 기준 구현체는 Claude Code이며, Cursor, Copilot, Gemini CLI, Codex, Cline, Windsurf 및 Aider가 공통 코어의 어댑터를 통해 연결됩니다. 라이선스는 MIT이며 특정 조직에 종속되지 않습니다.
빠른 시작
git clone https://github.com/vgtitov/bsl-ai-toolkit && cd bsl-ai-toolkit
bash onboard/onboard.sh
git clone https://github.com/vgtitov/bsl-ai-toolkit ; cd bsl-ai-toolkit
.\\onboard\onboard.ps1 # Windows; 1C 소스 코드는 ONEC_SRC_DIR 또는 -SrcDir <경로>에서 가져옵니다.
필요한 것: git, uv, java, rg, Claude Code (또는 다른 에이전트 — sh build.sh <agent>, Windows에서는 build.ps1을 참조하고, adapters/README.md를 참고하세요) 및 구성 파일을 파일로 내보내기(EDT 또는 Конфигуратор-XML). onboard가 자체적으로 선행 조건을 확인하고, 스킬과 .mcp.json 프로필 및 규칙을 배포하며, 환경 변수를 설정하고, git 훅을 설치하며, 자체 테스트를 수행합니다. 이후 에이전트를 재시작하고 MCP 서버들을 승인해야 합니다. 환경의 상태는 python scripts/doctor.py로 확인할 수 있습니다.
보안. 메타데이터 수정은 오직 테스트 데이터베이스에서만 검증됩니다. 라이브 데이터베이스(onec-data)에 대한 접근은 조사 중인 사용자 계정으로 읽기 전용(read-only)이며, 개인 식별 정보(ПДн)는 마스킹 처리됩니다. 경로와 자격 증명은 환경 변수를 통해 전달하며, 리포지토리나 에이전트와의 채팅 창에는 포함되지 않습니다. 자세한 내용은 SECURITY.md를 참고하세요.
에이전트가 직접 설정하게 하세요. 수동으로 설정할 필요가 없습니다. docs/AGENT_SETUP.md에서 완성된 프롬프트를 AI 에이전트에게 제공하기만 하면, 환경을 스스로 배포합니다 (사용자는 자신의 1C 소스 코드를 클론하고, 비밀 정보를 입력한 후, 테스트 데이터베이스를 게시하기만 하면 됩니다).**
- AI 도구 설치 가이드 (가이드 + 함정) — docs/AI_INSTALL_GUIDE.md.
- 2026년 10월 5일 이전에 클론되었나요? 리포지토리의 히스토리가 다시 작성되었습니다. — UPDATING.md 참조.
- 버전 관리 및 업데이트 — docs/AI_UPDATE.md (핵심은 semver 태그로 핀됩니다; AI는 스스로 업데이트됩니다).
- 환경 상태 확인 —
python scripts/doctor.py (사전 요구 사항 + .mcp.json의 MCP + 접근 권한).
세 가지 이식성 축: AGENTS.md (규칙) + SKILL.md (기술) + MCP (도구); 나머지 에이전트는 공통 핵심(core/)에서 최소한의 적응을 통해 연결됩니다 — adapters/ 참조. 1C-Bitrix는 아닙니다 (이는 PHP 기반 CMS이며 별도의 툴킷입니다).
Ponytail과 '먼저 존재하는 것을 확인하라' 규칙
- Ponytail (MIT, 저작자 Dietrich Gebert) — Claude Code 및 Codex용 플러그인: 코드를 작성하기 전에 에이전트는
프로필 기반 모드 ONEC_ACTIVE_PROFILE (명령어 온보딩에서 설정): analyst → off, 나머지 및 프로필 없는 경우 → lite.
bash onboard/onboard.sh
bash onboard/onboard.sh --ponytail-mode full
bash onboard/onboard.sh --no-ponytail
.\\onboard\onboard.ps1 -PonytailMode full
.\\onboard\onboard.ps1 -NoPonytail
scripts/update.sh / update.ps1도 Ponytail을 설치합니다 (수동으로 비활성화한 경우 제외); 건너뛰기: AI_TOOLKIT_NO_PONYTAIL=1.
재실행은 안전합니다: 플러그인은 기본 제공되는 claude plugin / codex plugin에 설치되며, 다른 설정은 건드리지 않습니다. 모드는 해당 위치에 아직 없는 경우에만 ~/.config/ponytail/config.json에 기록됩니다; 나중에 변경하려면 에이전트에서 /ponytail default <모드>를 사용합니다. Codex에 설치한 후에는 한 번 /hooks를 열고 Ponytail의 두 가지 훅을 허용해야 합니다. 훅에는 node가 필요합니다.
완전히 비활성화하는 방법 (설치 프로그램 및 업데이트에서도 존중): claude plugin disable ponytail@ponytail; Codex에서는 ~/.codex/config.toml 파일의 [plugins."ponytail@ponytail"]에서 enabled = false; 또는 /ponytail default off.
최소한으로 충분한 솔루션 (분석가 및 아키텍트)
분석 및 설계용 Ponytail 유사 기능: 에이전트는 개선 사항을 제안하기 전에 '문제 있음 → 개발 없음 → 표준형 및 BSP → 프로젝트 개선 → 최소 개선 → 새것' 사다리를 거치며, 문서에 어느 단계에서 멈췄는지 기록합니다. 문서를 줄이는 것이 아니라 해결책을 간소화합니다: 요구사항 명세서(ЧТЗ), 제품 패스포트(паспорта) 및 수락 기준은 완전히 작성됩니다. 스킬 1c-analyst, references/solution-ladder.md.
Stop-훅 scripts/discipline_gate.py는 '말로만' 진행하는 것을 막습니다: 검증(테스트, BSL LS, 스모크 테스트, 린터) 없이 코드가 변경되거나, 행동 없는 약속으로 작업이 끝나거나, 파일과 출처가 없는 비코드 과제에서 '완료됨'이라고 표시되는 것을 방지합니다. 현재 진행 상황만 확인합니다. 설치 프로그램 및 ~/.claude/settings.json 업데이트를 통해 설정되며 모든 프로젝트에서 작동합니다. 모드는 다음과 같습니다: AI_TOOLKIT_DISCIPLINE: 기본값은 warn(경고), enforce(모델에게 마무리하도록 요청), off. 설치 시에는 --no-discipline 또는 -NoDiscipline을 사용하고, 업데이트 시에는 AI_TOOLKIT_NO_DISCIPLINE=1을 설정하지 마십시오. 영구적으로 비활성화하려면 자체 설정에서 "env": {"AI_TOOLKIT_DISCIPLINE": "off"}를 지정하십시오. 설치 프로그램이 이를 덮어쓰지 않습니다. 훅 제거: python scripts/discipline_gate.py uninstall.
두 번째 의견: Codex, Copilot, 학습되지 않은 모델
Claude는 스스로 검증하지 않습니다: 리뷰 및 결정 검증은 다른 계열의 모델에 의해 수행됩니다. scripts/second_opinion.py review --base origin/main 또는 ask "컨텍스트와 질문"을 사용하면 일련의 과정을 거치며 설정된 것만 호출합니다: Codex (CLI 및 입력) → Copilot 또는 다른 기업용 어시스턴트 (AI_TOOLKIT_COPILOT_CMD — STDIN에서 질문을 읽는 명령어) → 학습되지 않은 모델 (오직 OPENROUTER_API_KEY와 AI_TOOLKIT_NOTRAIN=1일 때만; 저장 및 학습 기능이 없는 제공업체에 한함). 무료 모델은 호출되지 않습니다: 이들은 요청으로 학습되기 때문입니다. 만약 질문, 차분(diff), 또는 첨부 파일에 이메일 주소나 전화번호가 포함되어 있다면, 텍스트는 수정 없이 오직 신뢰할 수 있는 기업용 어시스턴트 (AI_TOOLKIT_COPILOT_CMD, 예: M365 Copilot)에게만 전송됩니다. Codex와 외부 모델은 건너뜁니다. 이러한 어시스턴트가 없으면 거부(코드 2)가 발생하며, 누구에게도 전송되지 않습니다. 아무도 답변하지 않으면 코드 2입니다.
⚠️ --risk critical|normal|low는 순서를 지정합니다: critical은 Codex가 먼저 실행됩니다 (제한이 적어 중요할 때 사용), normal(기본값)은 기업용 어시스턴트가 먼저, Codex는 예비로, low는 Codex 없이 진행됩니다.
ask --file 경로는 파일을 통째로 첨부합니다 (파일에도 이메일이나 전화번호가 없어야 거절되지 않습니다). 큰 차이점(review)은 자르지 않고 어시스턴트에게 첨부 파일로 전달됩니다. M365 Copilot용 어댑터(웹)는 scripts/copilot_adapter.py에 있습니다: Playwright가 필요하며, 한 번 로그인하면 됩니다; 연결은 AI_TOOLKIT_COPILOT_CMD를 통해 이루어집니다 (파일 상단 참조). 이것 없이는 체인이 진행되지 않습니다.
status는 어떤 것이 설정되었는지 보여줍니다.
기본적으로 두 번째 의견을 제시하는 것은 M365 Copilot입니다 (모두 제한이 많고, 데이터가 이미 기업 컨투어에 있기 때문): 온보딩 및 업데이트는 Microsoft Edge를 통해 확인하며, 어댑터(scripts/copilot_setup.py)가 이 브라우저로 작동합니다. M365 로그인은 한 번만 하면 됩니다 (python scripts/copilot_setup.py --login, 창이 열립니다). Codex는 고급 사용자용(--risk critical) 및 예비용입니다. 설치하지 않으려면 업데이트 시 --no-copilot / -NoCopilot, AI_TOOLKIT_NO_COPILOT=1을 사용하세요.
Codex는 온보딩과 업데이트를 통해 설치됩니다 (scripts/codex_setup.py: 공식 플러그인 openai/codex-plugin-cc 및 npm을 통한 CLI). 무료 버전도 포함하여 모든 ChatGPT 요금제가 사용 가능합니다: 한 번 로그인하면 됩니다 (codex login). 작업 코드를 위해 학습 기능을 꺼주세요: ChatGPT → Settings → Data Controls → Improve the model for everyone → Off. OpenAI는 일부 국가(러시아 연방 및 벨라루스 포함)에서 작동하지 않습니다: codex_setup.py --check를 사용하면 지리적 차단과 네트워크 오류를 구별할 수 있으며, 기업용 VPN이 필요합니다.
설치하지 않으려면 업데이트 시 --no-codex / -NoCodex, AI_TOOLKIT_NO_CODEX=1을 사용하세요.
uninstall/remove는 적절하지 않습니다: 다음 업데이트에서 플러그인이 다시 설치될 것입니다. 세션 동안은 stop ponytail을 사용하세요.
아이디어
RU 지역 AI 개발 시나리오 전체(‘바이브 코딩’, EDT/Cursor 내 에이전트)는 한 가지 문제에 직면해 있습니다: 모델이 1C의 세부 사항을 환각합니다 — 메서드를 지어내고, 패사드(매니저/객체/선택)를 혼동하며, 표준 구성 요소의 구성을 알지 못하고 호환성 모드를 파악하지 못합니다. 반면, 폼/СКД(데이터 스키마 및 보고서)/메타데이터는 생성의 ‘최종 방어선’으로 간주되어 수동으로 처리됩니다. 이 toolkit의 핵심 기능은 도구를 통한 검증 가능성입니다:
onec-code: 메모리가 아닌 실제 구성 요소 코드와 확장(두 컨투어 레이어 모두)을 검색합니다.bsl-ls: 수정할 때마다 BSL Language Server 진단을 수행합니다.onec_metadata: round-trip verify(테스트 데이터베이스에 로드 후 재내보내기 = 정확히 목표 차이(diff))를 통한 결정론적인 byte-perfect 메타데이터 수정(Конфигуратор-XML + EDT .mdo/.dcs)을 제공합니다. 이는 다른 도구들이 우회하는 바로 그 ‘최종 방어선’을 닫아줍니다.onec-ops: 운영 및 성능(트랜잭션 로그, 쿼리 계획, APDEX, Zabbix/Prometheus): 코딩뿐만 아니라 에이전트 기반 소프트웨어 엔지니어링(SWE)까지 다룹니다.onec-data: 연구 중인 사용자를 대상으로 하는 실시간 읽기 전용(read-only) 내부 보안(IB) 데이터 접근(진정한 RLS, 개인 식별 정보 마스킹).
아티팩트(요구사항 명세서 → 기술 설계)는 체계적인 원자적 작업과 검증된 코드로 변환됩니다. 한 문장으로 요약하면:
EDT/git 기반의 결정론적이고, 검증 가능하며 안전한 1C AI 개발 컨투어 — byte-perfect 메타데이터 및 운영까지 지원하는 agent-agnostic (LLM에 대한 제한적 접근 포함).
주변 도구와의 차이점
| 제공하는 기능 | 우리의 강조점 |
|---|
comol/ai_rules_1c, cursor_rules_1c | LLM을 위한 규칙/rules | 우리는 규칙 + 실제 코드에서의 MCP를 통한 실행, 단순 텍스트 지침이 아닙니다 |
| ... | | |
가장 큰 차이점: 테스트 데이터베이스에서 round-trip 검증을 수행하는 byte-perfect 메타데이터 수정 (폼, СКД, 속성).
비교는 프로젝트 설명(2026년 10월 5일)을 기준으로 했으며, 실제 코드를 기반으로 한 것이 아닙니다.
구성
bsl-ai-toolkit/
├── core/ # 단일 진실 공급원 (모든 AI 에이전트 공통)
│ ├── AGENTS.md # 규칙 (질문-도구, 컨투어 레이어, 메타데이터 게이트, 성능, 보안)
...
core/에서 생성된 파일들(CLAUDE.md, AGENTS.md, GEMINI.md, .mcp.json, .claude/)은 레포지토리를 클론한 직후 바로 작동하도록 커밋되어 있습니다. core/를 수정할 경우 → sh build.sh를 다시 실행하세요 (수동으로 생성된 파일은 편집하지 마세요).
크로스 플랫폼성 (실제 검증)
이식성은 두 축 모두에서 보장됩니다: 모든 AI 에이전트와 개발자의 모든 OS.
| 컴포넌트 | macOS | Linux | Windows |
|---|
메타데이터 엔진 onec_metadata, MCP, scripts/* | ✅ Python | ✅ Python | ✅ Python |
| ... | | | |
메타데이터 엔진은 순수 Python (OS 의존성 없음)이며, apply-레이어는 ssh/scp/tar를 사용합니다 (세 OS 모두에 존재). 또는 SSH가 없는 로컬 러너를 사용합니다 (플랫폼이 자체 머신일 경우). 생성된 에이전트 설정 파일들(CLAUDE.md, AGENTS.md, GEMINI.md, .claude/)은 커밋되어 있어 어떤 OS에서도 클론 직후 바로 작동합니다. 유일한 Windows 특이점은 원격 적용 대상인 1C 서버 자체이며, 개발자 머신의 OS는 중요하지 않습니다. | | | |
