| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 8 | 10 | 0% |
| Commands | 0 | 6 | 4 | 0% |
| Section tags | 1 | 4 | 5 | 10% |
What each file covers
Sections
0 shared · 8 only in A · 10 only in B- − NSForge Agent Harness
- − Goal
- − North Star
- − Working Style
- − Ground Truth: one command
- − Repo Layout (DDD)
- − Guardrails
- − Related Files
- + CLAUDE.md - Claude Code 專案指引
- + 注意事項
- + 0. 開發哲學 💡
- + 1. DDD 架構
- + 2. Python 環境（uv 優先）
- + 3. Memory Bank 同步
- + 4. Git 工作流
- + 可用 Skills
- + 💸 Memory Checkpoint 規則
- + Checkpoint 內容必須包含
Commands
0 shared · 6 only in A · 4 only in B- − python scripts/check.py
- − python scripts/check.py --json
- − python scripts/check.py --gates lint,type,test
- − mypy
- − uv run ...
- − python scripts/gen_capabilities.py
- + uv venv && uv sync --all-extras
- + uv add package-name
- + uv add --dev pytest ruff mypy
- + git-precommit
Section tags
1 shared · 4 only in A · 5 only in B- − code-style
- − architecture
- − security
- − do-not
- + setup
- + test
- + lint-format
- + git-pr
- + performance
- agent-behaviour
Line diff
u9401066/nsforge-mcp · AGENTS.md
@@ −1 @@
1# NSForge Agent Harness
2
3Workspace instructions for autonomous agents (Copilot, Cline, Codex, OpenHands,
4Hermes, …) working in the **Neurosymbolic Forge (NSForge)** repository.
5
6## Goal
7
8Help build and operate NSForge — an MCP server that turns *concepts* into
9verifiable, traceable *entities* (symbols → derivations → algorithms). The AI
10orchestrates; deterministic tools reify. See
11`docs/reification-ladder-direction.md` for the north star.
12
13## North Star
14
15> Every symbol / equation / value / line of code in a final result must have a
16> tool call as its "birth certificate" (provenance). The AI must not hand-derive
17> any of them.
18
19Success = the amount the AI computes by hand approaches zero.
20
21## Working Style
22
23- Use Traditional Chinese unless the user asks otherwise.
24- Prefer exact file paths, command output summaries, and verification results.
25- Offload mechanical/deterministic steps (symbolic calculation, simplification,
26 code generation) to tools — do not hand-derive formulas.
27- When changing behavior, add a focused regression test under `tests/`.
28
29## Ground Truth: one command
30
31Before and after changes, verify against the green baseline:
32
33```bash
34python scripts/check.py # all gates
35python scripts/check.py --json # machine-readable summary (for agents)
36python scripts/check.py --gates lint,type,test # subset
37```
38
39Gates: lint, format, type, import, manifest, test, bench, generic, provenance, harness, diff. Exit code 0 = green.
40(bench = derivation-correctness of `benchmarks/*.json` through the L3 orchestrator;
41generic = arbitrary unseen compositions derive correctly, proving NSForge is a
42derivation *calculus*, not a hand-built formula library; provenance = every
43benchmark derivation carries a complete tool-provenance ledger, no hand-derived leaks;
44harness = the harness self-checks its own invariants — version single-source,
45self-describing tools, and gate/doc parity — so agents can trust the signal.)
46
47## Repo Layout (DDD)
48
49- `src/nsforge/domain/`: pure domain models/value objects (no I/O)
50- `src/nsforge/application/`: use-cases / orchestration
51- `src/nsforge/infrastructure/`: adapters (sympy engine, formula sources, file I/O)
52- `src/nsforge_mcp/`: MCP tool layer + server wiring (`server.py`, `tools/`)
53- `docs/agent/capabilities.json`: machine-readable tool manifest (self-describing)
54
55## Guardrails
56
57- Keep `src/nsforge/domain` free of I/O and infrastructure imports.
58- Do not weaken `mypy` strict or skip gates just to make checks pass.
59- Prefer `uv run ...` so tools use the project venv.
60- Avoid destructive git ops (`reset --hard`, `clean -fdx`) unless asked.
61- Never commit secrets or generated outputs (`dist/`, `.venv/`, `data/`).
62- After adding/removing an `@mcp.tool`, regenerate the manifest:
63 `python scripts/gen_capabilities.py`.
64
65## Related Files
66
67- `docs/reification-ladder-direction.md` — architecture direction
68- `scripts/check.py` — verification harness (ground truth)
69- `scripts/gen_capabilities.py` — capability manifest generator
70- `.github/copilot-instructions.md` — Copilot rules
71- `memory-bank/activeContext.md` — current focus
72
u9401066/nsforge-mcp · CLAUDE.md
@@ +1 @@
1# CLAUDE.md - Claude Code 專案指引
2
3此文件為 Claude Code（Anthropic 的 AI 編程助手）提供專案上下文。
4當使用 Claude Code 時，它會自動讀取此文件以了解專案規範。
5
6---
7
8## 專案概述
9
10這是一個 **AI 輔助開發專案模板**，整合了：
11- 憲法-子法層級規則系統
12- Claude Skills 模組化技能
13- Memory Bank 專案記憶
14- DDD + DAL 獨立架構
15
16## 法規層級
17
18```
19CONSTITUTION.md ← 最高原則（不可違反）
20 │
21 ├── .github/bylaws/ ← 子法（細則規範）
22 │ ├── ddd-architecture.md
23 │ ├── git-workflow.md
24 │ └── memory-bank.md
25 │
26 └── .claude/skills/ ← 實施細則（操作程序）
27```
28
29## 核心原則
30
31### 0. 開發哲學 💡
32> **「想要寫文件的時候，就更新 Memory Bank 吧！」**
33>
34> **「想要零散測試的時候，就寫測試檔案進 tests/ 資料夾吧！」**
35
36- 不要另開檔案寫筆記，直接寫進 Memory Bank
37- 今天的零散測試，就是明天的回歸測試
38
39### 1. DDD 架構
40- Domain Layer 不依賴外部
41- DAL (Data Access Layer) 必須獨立
42- 使用 Repository Pattern
43- 參見：`.github/bylaws/ddd-architecture.md`
44
45### 2. Python 環境（uv 優先）
46```bash
47# 初始化
48uv venv && uv sync --all-extras
49
50# 安裝依賴
51uv add package-name
52uv add --dev pytest ruff mypy
53```
54- 參見：`.github/bylaws/python-environment.md`
55
56### 3. Memory Bank 同步
57每次重要操作必須更新：
58- `memory-bank/progress.md` - 進度追蹤
59- `memory-bank/activeContext.md` - 當前焦點
60- `memory-bank/decisionLog.md` - 重要決策
61
62### 4. Git 工作流
63提交前執行檢查清單：
641. Memory Bank 同步
652. README 更新（如需要）
663. CHANGELOG 更新
674. ROADMAP 標記
68
69## 可用 Skills
70
71| Skill | 用途 |
72|-------|------|
73| `git-precommit` | Git 提交前編排器 |
74| `ddd-architect` | DDD 架構輔助 |
75| `code-refactor` | 主動重構與模組化 |
76| `memory-updater` | Memory Bank 同步 |
77| `memory-checkpoint` | 記憶檢查點（Summarize 前外部化） |
78| `readme-updater` | README 智能更新 |
79| `changelog-updater` | CHANGELOG 自動更新 |
80| `roadmap-updater` | ROADMAP 狀態追蹤 |
81| `code-reviewer` | 程式碼審查 |
82| `test-generator` | 測試生成（Unit/Integration/E2E） |
83| `project-init` | 專案初始化 |
84
85## 💸 Memory Checkpoint 規則
86
87### 主動觸發時機
88- 對話超過 **10 輪** 時，主動建議 checkpoint
89- 完成 **重大功能** 後，主動執行 checkpoint
90- 使用者說要 **離開/等等繼續** 時，主動執行 checkpoint
91
92### Checkpoint 內容必須包含
93- 具體檔案路徑
94- 變更摘要
95- 下一步計畫
96- 重要決策（如有）
97
98### 觸發指令
99```
100「記憶檢查點」 / 「checkpoint」 / 「存檔」
101「保存記憶」 / 「sync memory」
102```
103
104## 常用指令
105
106```
107「準備 commit」 → 執行完整提交流程
108「快速 commit」 → 只同步 Memory Bank
109「建立新功能 X」 → 生成 DDD 結構
110「review 程式碼」 → 程式碼審查
111「更新 memory bank」 → 同步專案記憶
112```
113
114## 目錄結構約定
115
116```
117src/
118├── Domain/ # 核心領域（無外部依賴）
119├── Application/ # 應用層（用例編排）
120├── Infrastructure/ # 基礎設施（DAL、外部服務）
121└── Presentation/ # 呈現層（API、UI）
122```
123
124## 注意事項
125
126- 修改程式碼前先更新規格文檔
127- 程式碼是文檔的「編譯產物」
128- 遵循 Conventional Commits 格式
129- 使用繁體中文回應
130
@@ −1 +1 @@
1−# NSForge Agent Harness
1+# CLAUDE.md - Claude Code 專案指引
22
3−Workspace instructions for autonomous agents (Copilot, Cline, Codex, OpenHands,
4−Hermes, …) working in the **Neurosymbolic Forge (NSForge)** repository.
3+此文件為 Claude Code（Anthropic 的 AI 編程助手）提供專案上下文。
4+當使用 Claude Code 時，它會自動讀取此文件以了解專案規範。
55
6−## Goal
6+---
77
8−Help build and operate NSForge — an MCP server that turns *concepts* into
9−verifiable, traceable *entities* (symbols → derivations → algorithms). The AI
10−orchestrates; deterministic tools reify. See
11−`docs/reification-ladder-direction.md` for the north star.
8+## 專案概述
129
13−## North Star
10+這是一個 **AI 輔助開發專案模板**，整合了：
11+- 憲法-子法層級規則系統
12+- Claude Skills 模組化技能
13+- Memory Bank 專案記憶
14+- DDD + DAL 獨立架構
1415
15−> Every symbol / equation / value / line of code in a final result must have a
16−> tool call as its "birth certificate" (provenance). The AI must not hand-derive
17−> any of them.
16+## 法規層級
1817
19−Success = the amount the AI computes by hand approaches zero.
18+```
19+CONSTITUTION.md ← 最高原則（不可違反）
20+ │
21+ ├── .github/bylaws/ ← 子法（細則規範）
22+ │ ├── ddd-architecture.md
23+ │ ├── git-workflow.md
24+ │ └── memory-bank.md
25+ │
26+ └── .claude/skills/ ← 實施細則（操作程序）
27+```
2028
21−## Working Style
29+## 核心原則
2230
23−- Use Traditional Chinese unless the user asks otherwise.
24−- Prefer exact file paths, command output summaries, and verification results.
25−- Offload mechanical/deterministic steps (symbolic calculation, simplification,
26− code generation) to tools — do not hand-derive formulas.
27−- When changing behavior, add a focused regression test under `tests/`.
31+### 0. 開發哲學 💡
32+> **「想要寫文件的時候，就更新 Memory Bank 吧！」**
33+>
34+> **「想要零散測試的時候，就寫測試檔案進 tests/ 資料夾吧！」**
2835
29−## Ground Truth: one command
36+- 不要另開檔案寫筆記，直接寫進 Memory Bank
37+- 今天的零散測試，就是明天的回歸測試
3038
31−Before and after changes, verify against the green baseline:
39+### 1. DDD 架構
40+- Domain Layer 不依賴外部
41+- DAL (Data Access Layer) 必須獨立
42+- 使用 Repository Pattern
43+- 參見：`.github/bylaws/ddd-architecture.md`
3244
45+### 2. Python 環境（uv 優先）
3346 ```bash
34−python scripts/check.py # all gates
35−python scripts/check.py --json # machine-readable summary (for agents)
36−python scripts/check.py --gates lint,type,test # subset
47+# 初始化
48+uv venv && uv sync --all-extras
49+
50+# 安裝依賴
51+uv add package-name
52+uv add --dev pytest ruff mypy
3753 ```
54+- 參見：`.github/bylaws/python-environment.md`
3855
39−Gates: lint, format, type, import, manifest, test, bench, generic, provenance, harness, diff. Exit code 0 = green.
40−(bench = derivation-correctness of `benchmarks/*.json` through the L3 orchestrator;
41−generic = arbitrary unseen compositions derive correctly, proving NSForge is a
42−derivation *calculus*, not a hand-built formula library; provenance = every
43−benchmark derivation carries a complete tool-provenance ledger, no hand-derived leaks;
44−harness = the harness self-checks its own invariants — version single-source,
45−self-describing tools, and gate/doc parity — so agents can trust the signal.)
56+### 3. Memory Bank 同步
57+每次重要操作必須更新：
58+- `memory-bank/progress.md` - 進度追蹤
59+- `memory-bank/activeContext.md` - 當前焦點
60+- `memory-bank/decisionLog.md` - 重要決策
4661
47−## Repo Layout (DDD)
62+### 4. Git 工作流
63+提交前執行檢查清單：
64+1. Memory Bank 同步
65+2. README 更新（如需要）
66+3. CHANGELOG 更新
67+4. ROADMAP 標記
4868
49−- `src/nsforge/domain/`: pure domain models/value objects (no I/O)
50−- `src/nsforge/application/`: use-cases / orchestration
51−- `src/nsforge/infrastructure/`: adapters (sympy engine, formula sources, file I/O)
52−- `src/nsforge_mcp/`: MCP tool layer + server wiring (`server.py`, `tools/`)
53−- `docs/agent/capabilities.json`: machine-readable tool manifest (self-describing)
69+## 可用 Skills
5470
55−## Guardrails
71+| Skill | 用途 |
72+|-------|------|
73+| `git-precommit` | Git 提交前編排器 |
74+| `ddd-architect` | DDD 架構輔助 |
75+| `code-refactor` | 主動重構與模組化 |
76+| `memory-updater` | Memory Bank 同步 |
77+| `memory-checkpoint` | 記憶檢查點（Summarize 前外部化） |
78+| `readme-updater` | README 智能更新 |
79+| `changelog-updater` | CHANGELOG 自動更新 |
80+| `roadmap-updater` | ROADMAP 狀態追蹤 |
81+| `code-reviewer` | 程式碼審查 |
82+| `test-generator` | 測試生成（Unit/Integration/E2E） |
83+| `project-init` | 專案初始化 |
5684
57−- Keep `src/nsforge/domain` free of I/O and infrastructure imports.
58−- Do not weaken `mypy` strict or skip gates just to make checks pass.
59−- Prefer `uv run ...` so tools use the project venv.
60−- Avoid destructive git ops (`reset --hard`, `clean -fdx`) unless asked.
61−- Never commit secrets or generated outputs (`dist/`, `.venv/`, `data/`).
62−- After adding/removing an `@mcp.tool`, regenerate the manifest:
63− `python scripts/gen_capabilities.py`.
85+## 💸 Memory Checkpoint 規則
6486
65−## Related Files
87+### 主動觸發時機
88+- 對話超過 **10 輪** 時，主動建議 checkpoint
89+- 完成 **重大功能** 後，主動執行 checkpoint
90+- 使用者說要 **離開/等等繼續** 時，主動執行 checkpoint
6691
67−- `docs/reification-ladder-direction.md` — architecture direction
68−- `scripts/check.py` — verification harness (ground truth)
69−- `scripts/gen_capabilities.py` — capability manifest generator
70−- `.github/copilot-instructions.md` — Copilot rules
71−- `memory-bank/activeContext.md` — current focus
92+### Checkpoint 內容必須包含
93+- 具體檔案路徑
94+- 變更摘要
95+- 下一步計畫
96+- 重要決策（如有）
97+
98+### 觸發指令
99+```
100+「記憶檢查點」 / 「checkpoint」 / 「存檔」
101+「保存記憶」 / 「sync memory」
102+```
103+
104+## 常用指令
105+
106+```
107+「準備 commit」 → 執行完整提交流程
108+「快速 commit」 → 只同步 Memory Bank
109+「建立新功能 X」 → 生成 DDD 結構
110+「review 程式碼」 → 程式碼審查
111+「更新 memory bank」 → 同步專案記憶
112+```
113+
114+## 目錄結構約定
115+
116+```
117+src/
118+├── Domain/ # 核心領域（無外部依賴）
119+├── Application/ # 應用層（用例編排）
120+├── Infrastructure/ # 基礎設施（DAL、外部服務）
121+└── Presentation/ # 呈現層（API、UI）
122+```
123+
124+## 注意事項
125+
126+- 修改程式碼前先更新規格文檔
127+- 程式碼是文檔的「編譯產物」
128+- 遵循 Conventional Commits 格式
129+- 使用繁體中文回應
72130
