A project-level context layer that makes AI coding assistants truly understand your codebase.
Get your project AI-ready in 5 minutes.
AI coding assistants (Cursor, Copilot, Claude Code, etc.) can read files, but they still miss stable project context: business boundaries, architecture decisions, and hard-won team lessons.
AIEF gives your project a structured entry point - an AGENTS.md file plus a context/ knowledge base - so AI can load the right context consistently.
AGENTS.md is a cross-tool convention used by AI coding tools (some read it natively; others can be instructed to start from it). No vendor lock-in.
Most of the time you do not need adapters. If your tool does not read AGENTS.md by default, enable an adapter (see .ai-adapters/) or instruct the tool to start from AGENTS.md.
AIEF focuses on stable collaboration context, not model cleverness.
Why teams adopt it:
- Faster AI sessions with less repeated prompting
- Shared project rules across people and tools
- Incremental adoption (start small, expand when needed)
Most teams using AI in daily development hit the same issues:
- Rules are scattered - prompts and conventions live in personal habits
- Context is repeatedly re-explained - each task restarts from partial understanding
- Knowledge does not compound - decisions and pitfalls are not captured as team assets
- Onboarding is fragile - new members cannot reuse prior AI collaboration patterns
This framework solves these with one stable, project-level entry point.
Choose one path. Both are non-invasive and do not change your business code structure.
Default locale is zh-CN; pass --locale en if you want English templates.
Level cheat sheet for retrofit:
L0: minimum entry files onlyL0+:L0plus an auto-generated repo snapshot (recommended for existing projects)L1:L0+plus scaffold skeleton docs (business, tech, workflow, standards stubs)L2:L1plus full Skill/Command/Agent standards and experience management structureL3:L2plus cross-cutting patterns (phase router, experience mgmt, context loading) and.ai-adapters/README.md
# Step 1 - Run this in your project root
npx --yes @tongsh6/aief-init@latest new --locale enThis creates AGENTS.md and context/INDEX.md.
Step 2 - Open the generated AGENTS.md template and fill in:
- One-line project description
- Key constraints (e.g., directory boundaries, critical rules)
- Common commands (
build/test/run)
Keep it rough - short bullets are enough for L0.
Step 3 - Verify in 30 seconds:
AGENTS.mdexists in project rootcontext/INDEX.mdexists
Optional: Verify behavior in your AI tool:
- Ask: "List the key constraints from
AGENTS.mdas 3 bullets." It should match what you wrote.
Done. Start coding with your AI assistant from this fixed entry point.
# Step 1 - Run this in your project root
# L0+ keeps code untouched and also generates a repo snapshot
npx --yes @tongsh6/aief-init@latest retrofit --level L0+ --locale enThis creates AGENTS.md, context/INDEX.md, and context/tech/REPO_SNAPSHOT.md (L0+ level).
Step 2 - Check generated files:
AGENTS.md- fill in your project infocontext/tech/REPO_SNAPSHOT.md- review auto-detected stack, directory layout, and CI config hints (GitHub Actions, scripts, Makefile, etc.)
Step 3 - Verify in 30 seconds:
AGENTS.mdexists in project rootcontext/INDEX.mdexistscontext/tech/REPO_SNAPSHOT.mdexists (forL0+)
Optional: Verify behavior in your AI tool:
- Ask: "List the key constraints from
AGENTS.mdas 3 bullets." It should match what you wrote.
Done. Start coding with your AI assistant from this fixed entry point.
aief-init supports localized template generation:
# Chinese templates (default)
npx --yes @tongsh6/aief-init@latest new --locale zh-CN
# English templates
npx --yes @tongsh6/aief-init@latest retrofit --level L1 --locale enNotes:
- Supported locales:
zh-CN,en - Default locale:
zh-CN - Unsupported locale values automatically fall back to
zh-CNwith a warning L1scaffold includes localized templates forcontext/,workflow/,docs/standards/, andtemplates/
Generate AIEF assets directly under a dedicated base folder:
# Create AIEF assets under AIEF/
npx --yes @tongsh6/aief-init@latest retrofit --level L1 --base-dir AIEFWith --base-dir AIEF, assets are generated under:
AIEF/AGENTS.md(default; add--root-agentsto also write AGENTS.md in repo root)AIEF/context/AIEF/workflow/AIEF/docs/standards/AIEF/templates/AIEF/scripts/
By default, root-level AGENTS.md is not touched when --base-dir is provided. Use --root-agents if you want a copy in repo root as well.
Use these commands after initialization/retrofit to keep paths consistent and migrate assets safely:
# Diagnose AIEF project health (entry files + refs + script availability)
npx --yes @tongsh6/aief-init@latest doctor
# Machine-readable report for CI/scripts
npx --yes @tongsh6/aief-init@latest doctor --json
# Validate AIEF path references
npx --yes @tongsh6/aief-init@latest validate refs
# Validate and auto-fix deterministic cases
npx --yes @tongsh6/aief-init@latest validate refs --fix
# Migrate AIEF assets into a base directory (preview)
npx --yes @tongsh6/aief-init@latest migrate --to-base-dir AIEF --dry-run
# Execute migration + auto-fix + verify
npx --yes @tongsh6/aief-init@latest migrate --to-base-dir AIEFCommon flags:
--dry-run: preview changes without writing--force: overwrite existing files (useful when upgrading toL2/L3)--base-dir <path>: generate assets under a single directory--root-agents: also writeAGENTS.mdin repo root when--base-diris set
Doctor output example:
Doctor report for /path/to/project
[PASS] AGENTS.md entry file
[PASS] context/INDEX.md entry file
[WARN] scripts/aief.mjs available
hint: Run `aief-init retrofit --level L1` to enable `validate`/`migrate` delegation.
Summary: pass=2, warn=1, fail=0, blockingFail=0
Before: After:
your-project/ your-project/
├── src/ ├── src/
├── package.json ├── package.json
└── ... ├── AGENTS.md <- AI entry point
├── context/
│ ├── INDEX.md <- knowledge base nav
│ └── tech/
│ └── REPO_SNAPSHOT.md <- auto-generated (retrofit `L0+` only)
└── ...
A few files added. AI now has a stable, reusable way to read your project context.
Manual install (offline / intranet):
git clonethe AIEF repository, then copyAGENTS.mdandcontext/into your project. See init/ for details.
Package names
- Short alias package:
@tongsh6/aief-init - Canonical package:
@tongsh6/ai-engineering-framework-init
AIEF is built around three long-term engineering facts:
- AI needs a stable entry point to read project rules
- Projects need a long-lived context index
- Experience must be reusable across tasks and people
These are implemented with:
AGENTS.mdas the project-level AI entry pointcontext/as long-term context storagecontext/experience/as the compounding mechanismworkflow/as an optional collaboration enhancer
You do not need every file on day one. Recommended read/use order:
AGENTS.mdcontext/INDEX.mdcontext/business/context/tech/context/experience/workflow/(optional)docs/standards/(L1/L2 standards, optional).ai-adapters/(tool-specific, optional)
Condensed structure overview:
your-project/
├── AGENTS.md # AI entry point (tool-agnostic)
├── context/ # Project knowledge base
│ ├── INDEX.md # Navigation index
│ ├── business/ # Domain models, glossary
│ ├── tech/ # Architecture, API, conventions
│ └── experience/ # Lessons learned (compounding)
├── workflow/ # Multi-phase workflows (optional)
├── docs/standards/ # Skill/Command/Agent specs & patterns (optional)
└── .ai-adapters/ # Tool-specific configs (optional)
Only AGENTS.md and context/INDEX.md are required. Everything else is opt-in.
Organize project knowledge into three layers:
| Layer | Contents | Update Frequency |
|---|---|---|
| Business | Domain models, user stories, business rules | Low |
| Tech | Architecture, API docs, coding conventions | Medium |
| Experience | Lessons learned, best practices, post-mortems | High |
AI loads the right context automatically based on the task at hand - see AGENTS.md for the routing rules.
The real power: every time AI completes a task, valuable lessons get captured and indexed. Next time a similar task comes up, AI loads the relevant experience automatically.
First time -> Establish experience index
Second time -> Reuse experience, lower cost
Nth time -> Near-zero marginal cost
A built-in multi-phase workflow for complex tasks:
Trigger -> Route -> Phase Execution -> Validate -> Next Phase / Done
Built-in phases: proposal -> design -> implement -> review
You can also use OpenSpec, your own workflow, or skip this entirely.
All tools that support AGENTS.md work out of the box. For tool-specific enhancements:
| Tool | Config Path |
|---|---|
| Cursor | .ai-adapters/cursor/rules/ |
| GitHub Copilot | .ai-adapters/copilot/instructions.md |
| OpenCode | .ai-adapters/opencode/commands/ |
Works with OpenSpec for spec-driven development:
your-project/
├── AGENTS.md # AI Engineering entry point
├── context/ # Knowledge base
└── openspec/ # Spec-driven development
├── specs/
└── changes/
For existing projects, adopt incrementally:
| Level | Effort | What You Get |
|---|---|---|
| L0 | 5 min | AGENTS.md + context/INDEX.md (empty but present) |
| L0+ | 10 min | + auto-generated REPO_SNAPSHOT.md |
| L1 | 1-2 hrs | + one-page business doc + one-page tech doc |
| L2 | Optional | + workflow, experience templates, Skill/Command/Agent standards |
| L3 | Ongoing | + continuous experience compounding, cross-cutting patterns (auto-routing, experience management, context loading) |
Start at L0. Move up when you feel the need.
L0 is considered adopted once AGENTS.md and context/INDEX.md exist.
Reference Validation
When paths move (for example into AIEF/), use built-in reference checks:
# Validate references
node scripts/aief.mjs validate refs
# Validate and auto-fix deterministic cases
node scripts/aief.mjs validate refs --fix
# Unified verification entry (includes refs validation)
node scripts/aief.mjs verifyWhat it checks:
- Markdown path references in AIEF documents
- AIEF-related script paths in
package.jsonscripts templatePath(...)constants inside AIEF scriptscontext/experience/INDEX.mdintegrity and reachability
Asset Migration
Move AIEF assets into a single base directory and auto-repair references:
# Preview migration only
node scripts/aief.mjs migrate --to-base-dir AIEF --dry-run
# Execute migration + auto-fix refs + run verify
node scripts/aief.mjs migrate --to-base-dir AIEFBehavior:
- Migrates
context/,workflow/,docs/,templates/, and AIEF-related files underscripts/ - Auto-runs reference fixing after migration
- Auto-runs
aief verifyand prints a migration summary report - Idempotent: safe to run repeatedly
AIEF is a sidecar-style convention and does not modify your business code structure.
If you stop using it, remove:
AGENTS.mdcontext/
Build, runtime, and git history remain unaffected.
Best Practices
- Do not adopt the framework for its own sake
- Extract patterns from how your most effective team members work
- Turn those effective workflows into AI-readable context
- Turn experience into searchable docs
- Turn conventions into explicit rules
- Turn context into auto-loading strategies
- After each task, ask: what experience can be captured?
- Periodically organize the experience index
- Delete outdated knowledge
- Start with the minimal config
- Add complexity only when needed
- Regularly clean up unused configs
Branch Strategy & Contributing
| Branch | Purpose | Notes |
|---|---|---|
main |
Stable release | What users get by default |
develop |
Development | Integration testing for new features |
feature/* |
Feature branches | Created from develop, merged back |
Version tags: Semantic versioning - v1.0.0, v1.1.0, etc.
- Fork the repo
- Create a feature branch from
develop - Submit PR to
develop - Maintainers periodically merge
develop->mainand tag releases
v1.6.0- addL2/L3migration levelsv1.7.0- addvalidate refsandmigratesubcommandsv1.8.0- make@tongsh6/aief-inita thin wrapper delegating to canonical packagev1.8.1- documentation consistency pass + release/test workflow hardeningv1.9.0- adddoctorcommand for AIEF project health diagnostics
- Post-release checklist:
docs/release-post-checklist.md - Automated verifier:
node scripts/post-release-check.mjs <version>- Next iteration plan:
docs/ROADMAP_v1.9.0.md
- AGENTS.md Standard - Tool-agnostic AI guide standard
- Context Engineering - Context engineering methodology
- OpenSpec - Spec-driven development framework
- Cognitive Rebuild: Three Months with Speckit, Then I Gave Up - Core inspiration: the shift from tool-thinking to engineering-thinking
MIT