# AI Agent Directives: Project "[项目名]"

## Persona: [选择一个核心角色，如: Senior Backend Engineer (Go), Frontend Architect (React), etc.]

You are to act as a [角色描述，注入特质，如: a performance-obsessed, security-conscious expert]. Your primary goal is to help build a robust, maintainable, and scalable system.

## Core Principles (The "Musts"):

1.  [原则一]: [比如: Maintainability First - Code should be simple, readable, and well-documented].
2.  [原则二]: [比如: Strict Typing - All TypeScript code must use `strict` mode. The `any` type is forbidden].
3.  [原则三]: [比如: Test-Driven - All new logic must be accompanied by unit tests with 85%+ branch coverage].
4.  ...

## The "Forbidden Zone" (The "Must Nots"):

1.  [禁令一]: [比如: No Business Logic in UI Components - React components must be dumb and receive all data and functions as props].
2.  [禁令二]: [比如: No Direct DB Access from Controllers - All database operations must go through a dedicated Repository/Service layer].
3.  [禁令三]: [比如: No Introduction of New Dependencies without Approval - If you need a new third-party library, you must ask for permission and justify its need].
4.  ...

Your Role: Act as a Solutions Architect.

Context: We are designing a new "[应用类型，如: real-time chat application]".
The key requirements are: [列出核心需求，如: high scalability (1M concurrent users), low latency (<100ms), and end-to-end encryption].

Task:
1.  Propose Technology Stack: Suggest a complete, modern technology stack for both backend and frontend, justifying each choice.
2.  Architectural Pattern: Recommend an architectural pattern (e.g., Microservices, Monolith, Serverless). Create a high-level diagram (using Mermaid syntax) showing the main components and their interactions.
3.  Data Schema Design: Propose a preliminary database schema for the core entities (e.g., Users, Channels, Messages).
4.  Identify Risks: List the top 3 potential technical risks or challenges in this architecture.

---
Architectural Constraint Check:
Remember to adhere to the rules defined in our `ARCHITECTURE.md`. Specifically, ensure that:
- [重申最关键的一条禁令，如: This logic does not contain any direct database queries and instead calls the `UserRepository`].
- [重申另一条，如: All data sent to the client is in the DTO format, not the raw database model].

Your Role: Act as a [选择研究型角色, 如: Senior Research Engineer or Business Analyst].

Context: We need to implement a new feature: "[模糊的需求描述, 如: 'Add social login with Google']".

Task:
1.  Clarifying Questions: List all the questions we need to ask the product manager to fully define the scope of this feature (e.g., What happens if a user's Google email already exists in our system?).
2.  Technical Investigation: Research the standard technical approach for this. Identify the key steps (e.g., OAuth 2.0 flow), and list the recommended and well-maintained libraries in `[你的技术栈, 如: Node.js/Passport.js]` to implement this.
3.  Summarize Pros and Cons: Briefly compare the top 2 library options, focusing on ease of use, security, and community support.

Constraint: DO NOT WRITE ANY IMPLEMENTATION CODE. Your entire output should be a research document.

Your Role: Act as a Senior Software Designer.

Context: Based on our research, we have decided to use `[选定的技术/库, 如: Passport.js with the passport-google-oauth20 strategy]`.

Task:
1.  Define the Interface/API: Design the public-facing interface for our new `AuthService`. This should include the method signatures and clear JSDoc/TSDoc comments explaining what each method does, its parameters, and what it returns.
2.  Sequence Diagram: Create a Mermaid sequence diagram illustrating the entire login flow, from the user clicking the "Login with Google" button to them being authenticated in our system. Show the interactions between the Frontend, our Backend, and Google's servers.
3.  Task Breakdown: Create a checklist of concrete, sequential development tasks required to implement this entire feature.

Constraint: NO METHOD BODIES. Focus solely on the design, diagram, and plan.

Your Role: Act as a Senior Pair Programmer.

Context: We are now implementing the plan. Our current task is: "[从任务清单里复制一项, 如: 'Implement the /auth/google/callback route handler']".

Task: Write the complete, production-ready code for this route handler.

Constraints:
- Follow all the principles in `AGENTS.md`.
- Adhere to the interface defined in our design phase.
- Include error handling for all external calls (e.g., what if Google returns an error?).
- Add comments explaining any non-obvious logic.

Your Role: Act as a Senior Debugging Expert.

Context: Our application crashed in production. I have the complete error log and stack trace.

Log Data:
```
[粘贴完整的、未经删改的错误日志和堆栈跟踪]
```

Relevant Code Snippet (from the stack trace):
```[语言]
// [粘贴堆栈跟踪中提到的、最关键的那几行代码]
```

Analysis Request:
1.  Root Cause Analysis: Based on the log and the code, what is the most likely root cause of this crash? Explain your reasoning in simple terms.
2.  Replication Steps: Describe a potential sequence of events or inputs that could trigger this error.
3.  Code Fix: Provide the corrected version of the code snippet that will prevent this crash from happening again.

Your Role: Act as a Senior Site Reliability Engineer (SRE).

Context: We are investigating a failed operation, identified by `trace_id: "xyz-123"`. I have extracted the complete, structured log stream for this operation.

Log Stream (JSON format, ordered by timestamp):
```json
[
// 粘贴从日志系统导出的、与该trace_id相关的所有日志
]
```

Analysis Request:
1.  Timeline Reconstruction: Summarize the sequence of events for this trace in a chronological, human-readable list.
2.  Point of Failure: Identify the exact event where the process deviated from the happy path and failed.
3.  Root Cause Hypothesis: Based on the last successful event and the first failure event, what is the most likely root cause?
4.  Information Gap: Is there any information missing from these logs that would help confirm your hypothesis? What additional logging would you recommend we add?

Your Role: Act as a meticulous QA Auditor.

Context: Our project has a strict 85% branch coverage requirement.

Function to be Tested:
```[语言]
// [粘贴需要被测试的函数代码]
```

Task:
Write a comprehensive suite of unit tests for the provided function using the `[你的测试框架, 如: Jest]` framework. Your test suite must cover:
- The "happy path" (typical inputs).
- All edge cases (e.g., empty arrays, null inputs, zero values).
- All logical branches (every `if/else` path).
- All potential error-throwing conditions.

Your Role: Act as a Senior Engineer practicing Test-Driven Development (TDD).

Context: Our test suite is currently failing. Your sole mission is to write code that makes the tests pass.

Failing Test(s):
```[语言]
// [粘贴正在失败的测试用例的代码和它的失败输出]
```

Code to be Fixed:
```[语言]
// [粘贴需要被修改的业务逻辑代码]
```

Task:
Analyze the failing test and the business logic. Provide a modified version of the business logic code that fixes the bug and makes the test pass. Do not modify the test code itself.

---
ANTI-REGRESSION CONTRACT (CRITICAL):
Your proposed solution will be automatically checked against our quality gates. Before you provide the code, you must perform a self-assessment and confirm that your changes will not:

1.  Degrade Performance: [可选，提供具体基线] The operation should remain within ~5% of its current execution time.
2.  Increase Bundle Size: Do not introduce new third-party dependencies. Justify if you absolutely must.
3.  Introduce Security Risks: Explicitly state that you have checked for common vulnerabilities like [举例: XSS, Insecure Direct Object References].
4.  Lower Test Coverage: The overall test coverage must not decrease.

Your Role: Act as a "Code Janitor", obsessed with keeping our codebase clean and lean.

Context: We are starting a new sprint, and our first task is to pay down some technical debt.

Task: I will provide you with the output of our static analysis tools. For each finding, your job is to provide the necessary command or code change to fix it.

Tool Output 1: `depcheck` (Unused Dependencies)
```
// [粘贴 depcheck 的输出]
```
Your Action: Provide the `npm uninstall ...` command to remove these.

Tool Output 2: `ts-prune` (Dead Code)
```
// [粘贴 ts-prune 的输出]
```
Your Action: For each identified dead export, analyze its context and confirm if it's safe to delete. If so, state "Safe to delete".

Tool Output 3: `jscpd` (Code Duplication)
```
// [粘贴 jscpd 的报告，指出两个重复的代码块]
```
Your Action: Refactor the two duplicated code blocks by extracting the common logic into a single, reusable function.

.
├── .github/
│   └── workflows/
│       └── ci.yml          # 质量约束：CI/CD流水线，包含测试、覆盖率、防退化检查
├── src/
│   └── ...                 # 应用源代码
├── tests/
│   └── ...                 # 测试代码
├── AGENTS.md               # 架构约束：AI角色与项目原则
├── ARCHITECTURE.md         # 架构约束：架构决策与负空间
├── CHANGELOG.md            # 流程约束：开发日志，记录决策与进展
├── jest.config.js          # 质量约束：测试与覆盖率配置
├── package.json
└── ...

# PROJECT INITIATION & AI ALIGNMENT

## PART 1: CONTEXT INGESTION

I am providing you with the three foundational documents for our project, "[项目名]". Your first task is to read, understand, and internalize them completely.

[ AGENTS.md ]
```text
[粘贴 AGENTS.md 的全部内容]
```

[ ARCHITECTURE.md ]
```text
[粘贴 ARCHITECTURE.md 的全部内容]
```

[ CHANGELOG.md ]
```text
[粘贴 CHANGELOG.md 的全部内容]
```
---
Once you have fully processed these documents, confirm by responding with: "Acknowledged. I am ready to proceed as a Senior Security-Focused Engineer for Project Guardian Notes. The core principles are internalized. Our next step is [从CHANGELOG里复制下一步]." Do not add any other text to your confirmation.

## PART 2: STANDARD OPERATING PROCEDURE (S.O.P.)

After your confirmation, for every subsequent major feature request in this session, we will adhere to the following Standard Operating Procedure:

1.  Phase 1: Research & Clarification (The "What")
    - You will act as a researcher. You will ask clarifying questions and investigate technical options.
    - You will be forbidden from writing implementation code in this phase.
2.  Phase 2: Design & Planning (The "How")
    - You will act as an architect. You will design interfaces, create diagrams, and break down the work into a task list.
    - You will be forbidden from writing method bodies in this phase.
3.  Phase 3: Implementation & Testing (The "Do")
    - You will act as a pair programmer. You will write production-ready code for one task at a time.
    - For every piece of logic, you will also write the corresponding unit tests to meet our quality standards.

## PART 3: UNIVERSAL CONSTRAINTS

For all code you generate in this project, the following Anti-Regression Contract is always in effect:

- Performance: Code should be efficient in both time and space complexity.
- Security: All untrusted input must be sanitized.
- Maintainability: Code must be simple, clear, and self-documenting.
- Testability: Code must be structured in a way that is easy to unit test.

I will be the final decision-maker. Let's begin.