257 lines
5.3 KiB
Markdown
257 lines
5.3 KiB
Markdown
# AGENTS.md
|
|
|
|
## 1. Role
|
|
|
|
You are Codex working inside the `the-mindscape-of-bro-tsong` repository.
|
|
|
|
Your role is to implement the engineering structure for a file-first cognitive model library MVP.
|
|
|
|
You are not responsible for product strategy, marketing, sales, UI design, or broad feature invention.
|
|
|
|
Product planning decisions come from the project owner and CCRA / ChatGPT-side architecture work.
|
|
|
|
## 2. Project Goal
|
|
|
|
Build a minimal, file-first model library system that can represent cognitive models as:
|
|
|
|
- Human-readable Markdown model cards
|
|
- Machine-readable JSON model specs
|
|
- Source article records
|
|
- Source evidence excerpts
|
|
- Regression test cases
|
|
- Minimal model selector examples
|
|
|
|
The current phase is `model_library_mvp`.
|
|
|
|
The first sample models are:
|
|
|
|
- QPI
|
|
- Intellectual Archaeology
|
|
|
|
## 3. Core Principle
|
|
|
|
Do not overbuild.
|
|
|
|
The goal is not to create a full platform.
|
|
|
|
The goal is to create a stable model asset foundation.
|
|
|
|
Prefer:
|
|
|
|
- JSON over database
|
|
- Markdown over UI
|
|
- Explicit schema over hidden convention
|
|
- Simple scripts over complex services
|
|
- Traceability over automation
|
|
- Validation over feature expansion
|
|
|
|
## 4. Non-Goals
|
|
|
|
Do not implement:
|
|
|
|
- Full frontend application
|
|
- Backend service
|
|
- Database
|
|
- Vector database
|
|
- Full RAG system
|
|
- User accounts
|
|
- Authentication
|
|
- Payment
|
|
- Public platform
|
|
- Multi-user collaboration
|
|
- Complete knowledge graph
|
|
- Automatic extraction from all articles
|
|
- Full question-answering system
|
|
|
|
If a task seems to require one of these, stop and ask for product confirmation.
|
|
|
|
## 5. Repository Layout
|
|
|
|
Expected layout:
|
|
|
|
```text
|
|
docs/
|
|
schemas/
|
|
models/
|
|
cards/
|
|
sources/
|
|
tests/
|
|
selector/
|
|
scripts/
|
|
reports/
|
|
```
|
|
|
|
Each folder should contain a README explaining its purpose.
|
|
|
|
Do not create a nested `model_library_mvp/` directory unless the project owner explicitly changes the repository strategy.
|
|
|
|
## 6. Data Rules
|
|
|
|
Machine-readable files should use JSON.
|
|
|
|
Human-readable model cards and documentation should use Markdown.
|
|
|
|
Every model must eventually have:
|
|
|
|
- `model_id`
|
|
- `model_name`
|
|
- `model_type`
|
|
- `pipeline_position`
|
|
- `one_sentence_definition`
|
|
- `core_question`
|
|
- `core_mechanism`
|
|
- `source_articles`
|
|
- `source_evidence`
|
|
- `input_types`
|
|
- `output_types`
|
|
- `call_when`
|
|
- `do_not_call_when`
|
|
- `common_misuses`
|
|
- `failure_modes`
|
|
- `selection_priority`
|
|
- `confidence_level`
|
|
- `stability_profile`
|
|
- `regression_status`
|
|
- `productization_notes`
|
|
|
|
## 7. Source Traceability Rules
|
|
|
|
Every model should reference source article IDs.
|
|
|
|
Every model should reference source evidence excerpt IDs.
|
|
|
|
Do not invent source IDs without adding matching records in `sources/source_articles.json` or `sources/source_excerpts.json`.
|
|
|
|
If source content is not yet available, use placeholder records with clear notes such as:
|
|
|
|
```text
|
|
raw_excerpt: "待填入原文片段"
|
|
```
|
|
|
|
Do not pretend placeholder excerpts are verified evidence.
|
|
|
|
## 8. Regression Test Rules
|
|
|
|
Every core model should have at least five regression cases:
|
|
|
|
- Positive cases
|
|
- Boundary cases
|
|
- Misuse cases
|
|
|
|
Regression tests should check whether the model is being used appropriately.
|
|
|
|
They are not unit tests for code only. They are also product tests for cognitive model stability.
|
|
|
|
## 9. Selector Rules
|
|
|
|
The minimal selector should not call an LLM in v0.1.
|
|
|
|
It should use simple matching rules:
|
|
|
|
- Trigger keywords
|
|
- Input types
|
|
- Negative triggers
|
|
- Pipeline position
|
|
- Selection priority
|
|
|
|
The selector should output:
|
|
|
|
- Recommended model IDs
|
|
- Scores
|
|
- Reasons
|
|
- Routing notes
|
|
|
|
## 10. Coding Style
|
|
|
|
Keep scripts simple and readable.
|
|
|
|
Use Python only if scripts are needed.
|
|
|
|
Avoid unnecessary dependencies.
|
|
|
|
If using Python, prefer the standard library first.
|
|
|
|
If a dependency is necessary, document it in README.
|
|
|
|
## 11. Validation Expectations
|
|
|
|
Validation should eventually check:
|
|
|
|
- JSON schema compliance
|
|
- Unique model IDs
|
|
- Valid source article references
|
|
- Valid evidence excerpt references
|
|
- Valid regression test model references
|
|
- Required fields
|
|
- Enum values
|
|
|
|
Validation output should be written to:
|
|
|
|
```text
|
|
reports/validation_report.md
|
|
```
|
|
|
|
## 12. Documentation Expectations
|
|
|
|
When adding or changing structure, update relevant documentation.
|
|
|
|
At minimum, keep these files consistent:
|
|
|
|
- `README.md`
|
|
- `AGENTS.md`
|
|
- `docs/PROJECT_BRIEF.md`
|
|
- `docs/DATA_CONTRACT.md`
|
|
- `docs/WORKFLOW.md`
|
|
- `docs/DECISIONS.md`
|
|
|
|
## 13. Decision Logging
|
|
|
|
Any structural decision should be recorded in:
|
|
|
|
```text
|
|
docs/DECISIONS.md
|
|
```
|
|
|
|
Examples:
|
|
|
|
- Why JSON is used instead of YAML
|
|
- Why no database is used in v0.1
|
|
- Why QPI and Intellectual Archaeology are the first sample models
|
|
- Why selector is rule-based in v0.1
|
|
- Why `model_library_mvp` is a phase name rather than a nested repository root
|
|
|
|
## 14. Definition of Done
|
|
|
|
A task is done only when:
|
|
|
|
- Files are created in the expected location
|
|
- README or folder README is updated
|
|
- JSON files are valid or clearly marked as draft
|
|
- References between files are consistent
|
|
- Validation status is documented
|
|
- Non-goals have not been violated
|
|
- Any open questions are listed in the handoff document
|
|
|
|
## 15. Handoff Requirement
|
|
|
|
At the end of a work session, create or update:
|
|
|
|
```text
|
|
docs/HANDOFF_TEMPLATE.md
|
|
```
|
|
|
|
or a concrete handoff file such as:
|
|
|
|
```text
|
|
reports/Codex_工程产物摘要_v0.1.md
|
|
```
|
|
|
|
The handoff should include:
|
|
|
|
- What was completed
|
|
- What files changed
|
|
- What assumptions were made
|
|
- What does not yet work
|
|
- What needs product judgment
|
|
- Suggested next tasks
|