1. บทนำ
ใน Codelab นี้ คุณจะกำหนดค่าเอเจนต์การเขียนโค้ด AI (Antigravity) เพื่อให้ความปลอดภัยเป็นส่วนหนึ่งของลูปการพัฒนาตามปกติ แทนที่จะเป็นขั้นตอนการตรวจสอบแยกต่างหาก คุณจะติดตั้งชุดทักษะของ Agent ที่จะแนะนำ Agent ตลอดวงจรวางแผน → แดง → เขียว → รีแฟกเตอร์ และฮุก PreToolUse ที่สกัดกั้น git push สแกนไฟล์ที่เปลี่ยนแปลงด้วย CodeMender และส่งผลการค้นพบกลับไปยัง Agent พร้อมคำสั่งให้แก้ไขโดยทดสอบก่อน
ทักษะและฮุกมาจากเฟรมเวิร์ก Secure TDD Agent แบบโอเพนซอร์ส คุณจะติดตั้งเครื่องมือเหล่านี้ลงในพื้นที่ทำงาน ~/codemender-lab เดียวกันกับที่สร้างไว้ในพื้นฐาน CLI ของ CodeMender
สิ่งที่คุณจะได้เรียนรู้
- วิธีที่ Antigravity ค้นพบกฎ ทักษะ และฮุกของพื้นที่ทำงานในส่วน
.agents/ - ทักษะ Secure TDD ทั้ง 6 อย่างทำหน้าที่อะไรและแต่ละทักษะเป็นเจ้าของลูปในระยะใด
- วิธีที่ฮุก
PreToolUseรับการเรียกใช้เครื่องมือของ Agent ใน stdin และแสดงผลการตัดสินใจอนุญาต/ปฏิเสธ - วิธีที่ฮุกเกตความปลอดภัย (
security_gate_hook.sh) เรียกใช้cm find, จัดประเภทผลการค้นหาตามความรุนแรง, ติดตามการพยายามแก้ไข และส่งต่อด้วยcm verify - วิธียืนยันไปป์ไลน์ฮุกทั้งหมดแบบออฟไลน์ด้วยเครื่องมือสแกนจำลองก่อนที่จะชี้ไปยัง
cmจริง
ข้อกำหนดเบื้องต้น
- ผ่านหลักสูตรพื้นฐานเกี่ยวกับ CodeMender CLI ห้องทดลองนี้จะดำเนินการต่อในไดเรกทอรี
~/codemender-labและนำsample_app/,CONTEXT.md, ประวัติ git และ~/.codemender/config.yamlกลับมาใช้ซ้ำ - ติดตั้ง Antigravity แล้ว โดยสามารถเปิดโฟลเดอร์ในเครื่องเป็นพื้นที่ทำงานได้
- ติดตั้ง
git,jqและbashแล้ว สคริปต์ฮุกเป็น Bash ธรรมดาและทำงานบน Bash 3.2 ของ macOS รวมถึงเวอร์ชันที่ใหม่กว่า - สภาพแวดล้อมเสมือน Python จากข้อมูลเบื้องต้นเกี่ยวกับ CodeMender CLI (
~/codemender-lab/.venv) ที่ติดตั้ง Flask ไว้ - ความรู้พื้นฐานเกี่ยวกับการเขียนสคริปต์ของ Shell
2. การตั้งค่า Workspace
ขั้นตอนที่ 1: กลับไปที่ไดเรกทอรีห้องทดลอง
คำสั่งทั้งหมดในห้องทดลองนี้จะทำงานจาก ~/codemender-lab โดยมีสภาพแวดล้อมเสมือนจริงที่ทำงานอยู่
cd ~/codemender-lab && source .venv/bin/activate
ตรวจสอบว่าพื้นที่ทำงานจากห้องทดลองก่อนหน้านี้ยังคงอยู่และแผนผังการทำงานของคุณไม่มีการเปลี่ยนแปลง โดยทำดังนี้
ls sample_app/data_service.py CONTEXT.md .gitignore
git status --short
git status --short ไม่ควรพิมพ์อะไรเลย หากมีไฟล์แสดงอยู่ ให้คอมมิตไฟล์ก่อนดำเนินการต่อ
ขั้นตอนที่ 2: ตั้งชื่อ Branch main
เกตความปลอดภัยจะเปรียบเทียบความแตกต่างระหว่างแผนผังการทำงานกับ origin/main เพื่อตัดสินใจว่าจะสแกนไฟล์ใด หากไม่มีการอ้างอิงดังกล่าว ระบบจะเปลี่ยนไปใช้ HEAD~1 ซึ่งครอบคลุมเฉพาะคอมมิตล่าสุดเท่านั้น ตรวจสอบว่า Branch มีชื่อว่า main:
git branch -M main
ขั้นตอนที่ 3: เพิ่มจุดแรกเข้าของชุดโปรแกรมทดสอบ
ลูป TDD ที่ปลอดภัยจะขอให้ Agent เรียกใช้ python3 -m unittest discover -s tests หลังจากการแก้ไขทุกครั้ง ดังนั้นพื้นที่ทำงานจึงต้องมีไดเรกทอรี tests/ เริ่มต้นด้วยการทดสอบลักษณะเฉพาะ 1 รายการเพื่อให้ชุดโปรแกรมมีสิ่งที่ทำงานได้จริง ดังนี้
mkdir -p tests && touch tests/__init__.py
cat << 'EOF' > tests/test_data_service.py
import unittest
from sample_app.data_service import hash_password
class HashPasswordTests(unittest.TestCase):
def test_returns_hex_digest(self):
digest = hash_password("hunter2")
self.assertIsInstance(digest, str)
int(digest, 16) # raises ValueError if not hexadecimal
if __name__ == "__main__":
unittest.main()
EOF
python3 -m unittest discover -s tests
คุณควรเห็น Ran 1 test และ OK
ขั้นตอนที่ 4: ขยาย .gitignore และยืนยัน
เพิ่มไฟล์รันไทม์ที่ห้องทดลองนี้สร้างขึ้นลงใน .gitignore แล้วคอมมิตเกณฑ์พื้นฐาน ดังนี้
printf '.security-gate/\nusers.db\n*.bak\n' >> .gitignore
git add -A && git commit -m "Add test suite entry point for Secure TDD"
3. การติดตั้งไฟล์เฟรมเวิร์ก
ทักษะ, กฎ, Hook และโปรแกรมทดสอบอัตโนมัติแบบออฟไลน์ทั้งหมดจะอยู่ในไดเรกทอรี .agents/ เดียวกัน แทนที่จะพิมพ์ Bash ประมาณ 800 บรรทัดด้วยตนเอง ให้โคลนเฟรมเวิร์กและคัดลอกไดเรกทอรีนั้นลงในพื้นที่ทำงานของคุณ โดยทำดังนี้
git clone --depth 1 https://github.com/h3xar0n/secure-tdd-agent-framework.git /tmp/secure-tdd
cp -R /tmp/secure-tdd/.agents ./.agents
rm -rf /tmp/secure-tdd
ยืนยันเลย์เอาต์
find .agents -type f | sort
.agents/hooks.json
.agents/lib/README.md
.agents/lib/engine_codemender.sh
.agents/lib/engine_semgrep.sh
.agents/lib/gate_common.sh
.agents/rules/secure_tdd_workflow.md
.agents/security_gate_hook.sh
.agents/skills/defensive-developer/SKILL.md
.agents/skills/history-context-seeder/SKILL.md
.agents/skills/local-refactor-scanner/SKILL.md
.agents/skills/security-test-writer/SKILL.md
.agents/skills/skill-evolution-updater/SKILL.md
.agents/skills/threat-model-assessor/SKILL.md
.agents/tests/mocks/cm
.agents/tests/mocks/semgrep
.agents/tests/run_tests.sh
ตรวจสอบว่าจุดแรกเข้าของฮุกเรียกใช้ได้โดยทำดังนี้
chmod +x .agents/security_gate_hook.sh
ls -l .agents/security_gate_hook.sh
ส่วนที่เหลือของห้องทดลองนี้จะอธิบายสิ่งที่คุณเพิ่งติดตั้งไปทีละส่วน
4. กฎเวิร์กโฟลว์ที่เปิดตลอดเวลา
ระบบจะโหลดทักษะตามต้องการเมื่อ Agent ตัดสินใจว่าคำอธิบายของทักษะตรงกับงาน ต้องมีบางอย่างบอกให้ Agent เข้าถึงข้อมูลเหล่านั้นตามลำดับที่ถูกต้อง นั่นคือหน้าที่ของ .agents/rules/secure_tdd_workflow.md Frontmatter ของ Gem จะตั้งค่า trigger: always_on ดังนั้นระบบจะแทรกกฎลงในทุกเทิร์น ดังนี้
---
trigger: always_on
---
# Test-Driven Development with Integrated Security (Secure TDD) Workflow Rule
You MUST strictly follow this 4-phase cyclical workflow for all feature implementations, refactors, and bug fixes:
1. **Phase A (Plan, Scope & Threat Model)**:
- Ingest `CONTEXT.md` to review established project conventions, approved helpers, and trust zones.
- Decompose feature requirements, user stories, and acceptance criteria.
- Invoke the **Threat Model Assessor Skill** to perform a STRIDE evaluation and generate/update `threat_model.md`.
2. **Phase B (Functional & Security Test-First - RED)**:
- Invoke the **Security Test Writer Skill**.
- Author unit and integration tests asserting functional behavior (happy paths, business logic), edge cases, AND security boundaries (rejecting invalid inputs, unauthenticated requests, unauthorized role access).
- Execute the tests and confirm they FAIL for the expected assertion reason (RED).
3. **Phase C (Feature Implementation & Defensive Code - GREEN)**:
- Invoke the **Defensive Developer Skill**.
- Author clean, modular production code strictly required to satisfy the functional tests and security assertions.
- Apply input validation allow-lists, parameterized queries, and least-privilege payload returns.
- Run the tests to confirm they are GREEN.
4. **Phase D (Refactor, Quality & Scan)**:
- Invoke the **Local Refactor & Scanner Skill**.
- Clean up code, eliminate duplication, and verify 100% passing test regressions.
- Run fast deterministic checks (secrets, dependencies, local SAST).
- Conduct a guided AI review to verify architectural boundaries and eliminate logic bypasses.
- Ensure diffs remain small, surgical, and preserve baseline stability.
5. **Continuous Evolution**:
- If a new pattern, helper function, or architectural convention was introduced, invoke the **Skill Evolution Updater Skill** to document the lesson into `CONTEXT.md` or the appropriate `SKILL.md`.
6. **Multi-Finding Remediation Protocol**:
- When resolving multiple findings from a scan or security gate rejection, iterate sequentially one finding at a time:
1. Author one discrete boundary test for the finding (RED).
2. Implement the minimal defensive fix (GREEN).
3. Verify local tests pass before moving to the next finding.
- Avoid applying multi-finding changes in a single unverified edit. Run the full regression test suite only after all individual findings have passed their discrete TDD cycle.
กฎจะอ้างอิง CONTEXT.md ซึ่งคุณสร้างไว้ในพื้นฐาน CLI ของ CodeMender ไฟล์เดียวกับที่นำทาง cm fix ไปยังรูปแบบการค้นหาที่มีพารามิเตอร์จะนำทางการวางแผนของ Agent ด้วย รายการที่ 6 มีความสำคัญมากที่สุดสำหรับห้องทดลองนี้ เนื่องจากเป็นสิ่งที่ Agent จะปฏิบัติตามเมื่อเกตความปลอดภัยปฏิเสธการพุชที่มีการค้นพบหลายรายการพร้อมกัน
5. ทักษะ 6 ประการของ Agent
ทักษะแต่ละรายการคือไดเรกทอรีที่มี SKILL.md พร้อม YAML Front Matter ต้องระบุข้อมูลใน 2 ช่องต่อไปนี้
name: ตัวระบุที่เป็นตัวพิมพ์เล็กและมีขีดกลางdescription: สิ่งที่ทักษะทำและเวลาที่ควรใช้ Agent จะอ่านเฉพาะช่องนี้เมื่อตัดสินใจว่าจะโหลดทักษะแบบเต็มหรือไม่ ดังนั้นคำอธิบายแต่ละรายการด้านล่างจึงระบุด้วยว่าทักษะนี้ไม่เหมาะกับอะไร
ทักษะ | ระยะ | วัตถุประสงค์ |
| คำตอบ: แผน | กำหนดขอบเขตฟีเจอร์ เรียกใช้ STRIDE เขียน |
| ข: แดง | เขียนการทดสอบฟังก์ชันและการทดสอบขอบเขตที่ล้มเหลวด้วยเหตุผลที่ถูกต้อง |
| C: เขียว | เขียนโค้ดขั้นต่ำที่ทำให้การทดสอบเป็นสีเขียวโดยใช้รูปแบบที่ปลอดภัย |
| ง: รีแฟกเตอร์ | ล้างข้อมูล เรียกใช้ชุดโปรแกรมทั้งหมด เรียกใช้เครื่องมือสแกนในเครื่อง ตรวจสอบความแตกต่าง |
| ต่อเนื่อง | บันทึกรูปแบบใหม่ในไฟล์ |
| การเริ่มต้นใช้งาน | ขุดประวัติ Git เพื่อสร้าง |
เนื้อหาทั้งหมดจะแสดงอยู่ด้านล่างเพื่อให้คุณเห็นว่าส่วนหน้าและวิธีการทำงานร่วมกันอย่างไร
1. threat-model-assessor (ระยะที่ 1)
.agents/skills/threat-model-assessor/SKILL.md:
---
name: threat-model-assessor
description: Plans feature architecture, functional requirements, and evaluates STRIDE security boundaries in Phase A Plan. Use when scoping new features or bug fixes, defining user stories and acceptance criteria, identifying trust boundaries, and generating or updating threat_model.md. Do not use for writing test assertions, implementing production code, or running local scanners.
---
# Planning, Requirements & Threat Model Assessor Skill (Phase A: Plan Phase)
## Overview
Decompose feature requirements, establish functional acceptance criteria, and map trust boundaries before any production code is authored. This skill pairs functional engineering scoping with STRIDE threat modeling at the planning stage, establishing the functional and security acceptance criteria consumed by downstream test writers.
## System Sequence
1. **Ingest Context**: Read `CONTEXT.md` to identify existing architecture, trust boundaries, approved libraries, and conventions.
2. **Decompose Requirements**:
- Define user stories, input/output data contracts, and functional acceptance criteria.
- Break complex tasks into bite-sized, testable implementation stages.
3. **Apply STRIDE Threat Modeling**:
- **Spoofing**: Authentication boundaries, session validation, caller identity checks.
- **Tampering**: Input payload validation, integrity checks, parameter tampering.
- **Repudiation**: Audit logging of critical state transitions.
- **Information Disclosure**: Restrict error responses, prevent stack trace leaks, mask PII/secrets.
- **Denial of Service**: Resource limits, payload size constraints, timeout limits.
- **Elevation of Privilege**: Role-Based Access Control (RBAC), caller authorization checks.
4. **Generate/Update `threat_model.md`**:
- Store or update `threat_model.md` at the workspace root with both Functional & Security Acceptance Criteria.
## Target Output Artifact (`threat_model.md`)
```markdown
# Feature Plan & Threat Model: [Feature Name]
## 1. Functional Scope & Requirements
- **Goal**: [Description of feature or bug fix]
- **Deliverables**: [Endpoints, functions, or modules to create/modify]
- **Functional Acceptance Criteria**: [Expected behaviors and outputs]
## 2. Entry Points & Data Inputs
- Endpoint / Input: [Path / Name]
- Format & Constraints: [Schema / Type]
## 3. Trust Boundaries & Access Controls
- Authentication: [Required / Public]
- Authorization Role: [User / Admin]
## 4. STRIDE Threat Matrix & Security Acceptance Criteria
- [STRIDE Category]: [Threat Description] -> [Required Mitigation & Test Assertion]
```
2. security-test-writer (ระยะที่ 2)
.agents/skills/security-test-writer/SKILL.md:
---
name: security-test-writer
description: Authors test-first unit and integration tests covering functional behavior, edge cases, and security boundaries in Phase B RED. Use when creating failing automated tests before writing production code, asserting HTTP status codes and contract responses, establishing boundary limits, or asserting that exploit payloads are rejected cleanly. Do not use for threat modeling during initial planning, writing production feature code, or running refactor sweeps.
---
# QA & Security Test Writer Skill (Phase B: RED Phase)
## Overview
Translate functional requirements and security criteria from `threat_model.md` and `CONTEXT.md` into executable test cases that fail initially (RED), asserting expected business logic, edge-case handling, and security boundaries before production code is authored.
## Three Verification Pillars
1. **Behavior-Driven Outcomes**:
- Assert strictly on API/HTTP outcomes (status codes 200/302 for valid requests, 400/401/403 for invalid/unauthorized, expected JSON responses) rather than mocking internal private methods.
2. **Strict Test Isolation**:
- Ensure test setup and teardown cleanly isolate state (e.g., transaction rollbacks, fresh test contexts) so state never bleeds between test runs.
3. **Integration Over Fragile Mocking**:
- Utilize local test databases or real server contexts rather than fragile fake mocks to verify realistic functional and security behavior.
## Execution Sequence
1. **Consume Requirements & Threat Model**: Read the task scope, `threat_model.md`, and `CONTEXT.md` for functional requirements and security acceptance criteria.
2. **Author Test Cases**:
- **Functional Happy Path**: Test validating standard user workflows and expected output payloads.
- **Functional Edge Cases**: Test missing optional/required parameters, boundary limits, and unexpected data types.
- **Authentication Boundary**: Assert requests without valid credentials return `401 Unauthorized`.
- **Authorization Boundary**: Assert requests with insufficient role/scope return `403 Forbidden`.
- **Input Validation**: Assert malformed, oversized, or un-whitelisted data returns `400 Bad Request`.
- **Exploit Payloads**: Assert dangerous inputs (SQLi, path traversal `../../`, XSS) are rejected cleanly.
3. **Execute & Verify RED**:
- Run the project's test command (e.g., `pytest`, `python3 -m unittest discover -s tests`).
- **Requirement**: Confirm the tests fail due to the expected missing feature logic/boundary assertion and not due to a syntax or import error.
4. **Multi-Finding Handling**:
- When remediating multiple scanner findings, write and verify one boundary test for one finding at a time before proceeding to defensive implementation.
3. defensive-developer (ระยะ C)
.agents/skills/defensive-developer/SKILL.md:
---
name: defensive-developer
description: Implements clean, maintainable production code to deliver features and satisfy functional and security test assertions in Phase C GREEN. Use when writing minimal, modular production code to turn failing RED tests GREEN, applying input validation allow-lists, enforcing explicit caller authorization, and using parameterized sinks and least-privilege payloads. Do not use for authoring initial tests, performing initial threat modeling, or running post-implementation security scans.
---
# Feature Implementation & Defensive Developer Skill (Phase C: GREEN Phase)
## Overview
Implement clean, modular production code that delivers the requested feature or bug fix and satisfies all functional, edge-case, and security assertions from Phase B while adhering to defensive design principles and project conventions in `CONTEXT.md`.
## Three Defensive Pillars
1. **Simple Input Validation**:
- Enforce type, size, and strict allow-list validation on all incoming data.
- Prefer structured parsing libraries (`pydantic`, `urllib.parse`) over complex regex which may be vulnerable to ReDoS.
2. **Explicit Authorization**:
- Validate caller identity and match required permissions before invoking business logic.
3. **Least Privilege & Safe Operations**:
- Parameterize all SQL/database queries.
- Use canonical path checks (`os.path.realpath`) with prefix boundary validation.
- Return only the minimal data payload required by the client.
- Mask credentials, PII, and omit internal stack traces in error messages.
## Execution Sequence
1. **Inspect Failing Tests & Rules**: Review the functional requirements, failing tests from Phase B, and conventions in `CONTEXT.md`.
2. **Author Clean Production Code**:
- Implement the business logic and algorithms required to satisfy the functional feature requirements.
- Apply defensive patterns (e.g. `utils.security.resolve_safe_path`, parameterized SQL statements, `pydantic` schemas).
3. **Confirm GREEN State**:
- Run the project test suite.
- Verify that all functional and security tests pass cleanly without errors.
4. **Multi-Finding Handling**:
- When remediating multiple scanner findings, apply the minimal fix for the current failing boundary test, confirm GREEN, then proceed to the next finding's test-fix cycle.
4. local-refactor-scanner (ระยะที่ 4)
.agents/skills/local-refactor-scanner/SKILL.md:
---
name: local-refactor-scanner
description: Refactors code for quality and maintainability, executes full test suite regression passes, and runs local deterministic security and lint scans in Phase D REFACTOR. Use when cleaning up code structure and eliminating duplication after tests pass, running local linters and fast offline scanners for secrets or dependencies, executing full regression test suites, and performing guided code reviews. Do not use for implementing initial feature logic, writing failing test-first suites, or modifying architectural threat models.
---
# Code Refactoring, Quality & Local Scanner Skill (Phase D: REFACTOR Phase)
## Overview
Refactor implementation for clean code structure, modularity, and maintainability while ensuring 100% passing test regressions and blocking pattern-based security flaws locally prior to commit.
## Verification Guardrails
1. **Code Quality & Refactoring**:
- Clean up boilerplate, eliminate dead code, and centralize common utilities.
- Improve variable naming, modularity, and type annotations without altering verified behavior.
2. **Deterministic Scans (Fast & Offline)**:
- **Secrets**: Check diffs for plaintext credentials, tokens, or private keys.
- **Dependencies**: Flag unpinned dependencies or known CVEs in new packages.
- **Rules-Based SAST**: Run local SAST rules on modified files (`semgrep scan --config auto --json` or `cm find`).
3. **Guided AI Review**:
- Audit architecture and design issues that static tools miss.
- Review business logic and edge cases for bypasses or regression risks.
4. **Small Diffs & Regression QA**:
- Run the complete project test suite to verify zero regressions across existing and new tests.
- Ensure the diff contains only surgical changes directly related to the task scope.
## Execution Sequence
1. Review the git diff of modified files (`git diff`).
2. Refactor code for clarity, maintainability, and helper reuse.
3. Run local linters and security scanners on changed files.
4. Run the full test suite to guarantee 100% passing tests.
5. **Continuous Evolution**: Capture new conventions in `CONTEXT.md` and suggest/apply updates to `SKILL.md` instructions via `skill-evolution-updater` to permanently prevent recurrence of issues.
5. skill-evolution-updater (การพัฒนาอย่างต่อเนื่อง)
.agents/skills/skill-evolution-updater/SKILL.md:
---
name: skill-evolution-updater
description: Extracts systemic conventions from resolved bugs, patterns, and refactors to update CONTEXT.md and agent skills for continuous evolution. Use when capturing durable coding rules, architectural conventions, or recurring fix patterns into CONTEXT.md after a task or bug fix, updating skill instructions to prevent recurrence of errors, and logging gate findings to findings-log.ndjson. Do not use for writing feature code, authoring unit tests, or running pre-push scanner pipelines.
---
# Skill & Conventions Evolution Updater (Continuous Evolution)
## Overview
Ensure the development team and agent fleet continuously learn from local fixes, architecture decisions, and refactoring patterns so that systemic quality and security standards are retained permanently.
## Continuous Feedback Mechanism
```
+-----------------------------------------------------------------+
| CONTINUOUS FEEDBACK LOOP |
| |
| 1. Local Fix / Feature Verified (Refactor Phase) |
| v |
| 2. Systemic Lesson Extracted (Best practices & conventions) |
| v |
| 3. Feed Back to Shared Specs (Update SKILL.md/CONTEXT.md) |
| v |
| 4. Context Seeding (All future agents inherit rules upfront) |
+-----------------------------------------------------------------+
```
## Execution Sequence
1. **Analyze Remediation Diff**: Review the code change or bug fix just completed.
2. **Extract the Systemic Rule**:
- Formulate an actionable, project-specific rule.
- Example: *"When implementing redirects, always use `utils.security.safe_redirect()` with allow-listed domains."*
- Example: *"All JSON endpoints must validate request body using Pydantic schemas."*
3. **Update Shared Specifications**:
- **Update `CONTEXT.md`**: Append the rule under `## 4. Continuous Evolution: Auto-Evolved Conventions`.
- **Update Skills (if applicable)**: If a general coding anti-pattern or QA procedure was refined, update the relevant `SKILL.md`.
4. **Persist Insight**: Append the raw structured event to `.security-gate/findings-log.ndjson` for audit traceability.
6. history-context-seeder (การเริ่มต้นใช้งาน)
.agents/skills/history-context-seeder/SKILL.md:
---
name: history-context-seeder
description: Analyzes repository Git history for past bug fixes, architectural conventions, and security patterns to seed CONTEXT.md on onboarding. Use when first adopting the framework in an existing repository, mining historical commits and bug fixes for recurring risk areas, or populating the initial CONTEXT.md baseline with established conventions and helpers. Do not use for routine feature development, authoring test suites, or running the inner TDD loop on active tasks.
---
# History & Architectural Context Seeder Skill (Repository Onboarding)
## Overview
Analyzes the repository's Git history and past fix commits to extract recurring bug patterns, architectural conventions, and security patterns, seeding `CONTEXT.md` during initial repository onboarding.
## Execution Sequence
1. **Analyze Git Log**:
- Inspect commits touching bug fixes, refactors, and sensitive modules:
`git log --grep="fix\|bug\|refactor\|vuln\|security\|patch" -n 50 --oneline`
2. **Extract Historical Lessons**:
- Identify which files and modules have historically been prone to bugs or regressions.
- Extract past patterns and architectural conventions established by maintainers.
3. **Seed `CONTEXT.md`**:
- Populate `CONTEXT.md` with known architectural risk areas, sensitive directories, approved helpers, and custom project conventions.
คุณจะไม่ใช้ทักษะนี้ในห้องปฏิบัติการเนื่องจากมี CONTEXT.md อยู่แล้ว แต่เป็นทักษะที่ต้องใช้เมื่อคุณนำเฟรมเวิร์กไปยังที่เก็บซึ่งมีประวัติการใช้งานมานานหลายปีและไม่มีข้อตกลงที่เป็นลายลักษณ์อักษร
6. การกำหนดค่า Antigravity Hook
.agents/hooks.json จะบอกให้ Antigravity เรียกใช้เกตความปลอดภัยก่อนคำสั่งเทอร์มินัลที่ Agent เรียกใช้
{
"security-gate": {
"PreToolUse": [
{
"matcher": "run_command|.*:run_command|run_shell_command|Bash",
"hooks": [
{
"type": "command",
"command": "bash -c 'if [ -x ./security_gate_hook.sh ]; then exec ./security_gate_hook.sh; else exec ./.agents/security_gate_hook.sh; fi'",
"timeout": 120
}
]
}
]
}
}
รายละเอียดบางอย่างเกี่ยวกับไฟล์นี้จะอธิบายการออกแบบสคริปต์ที่เปิดขึ้น ดังนี้
matcherเป็นนิพจน์ทั่วไปสำหรับชื่อเครื่องมือ ไม่ใช่ข้อความคำสั่งPreToolUseจะเริ่มทำงานก่อนที่เครื่องมือจะทำงาน และตัวจับคู่จะตัดสินใจว่าจะใช้เครื่องมือใดrun_commandเป็นเครื่องมือเทอร์มินัลของ Antigravity ส่วนทางเลือกอื่นๆ จะครอบคลุมตัวแปรเนมสเปซของปลั๊กอินและแพลตฟอร์มตัวแทนอื่นๆ ที่แชร์ไฟล์เหล่านี้ ตัวจับคู่อย่างgit push*จะไม่เริ่มทำงานเนื่องจากไม่มีเครื่องมือที่ชื่อนั้น การกรองคำสั่งจริงจะเกิดขึ้นภายในสคริปต์- ฮุกจะรับการเรียกใช้เครื่องมือใน stdin Antigravity จะส่งเพย์โหลด JSON เช่น
{"toolCall": {"name": "run_command", "args": {"CommandLine": "git push origin main"}}, ...}สคริปต์จะอ่าน.toolCall.args.CommandLineและออกทันทีพร้อมกับการตัดสินใจอนุญาตสำหรับสิ่งที่ไม่ใช่git push - ไดเรกทอรีที่ใช้งานอยู่คือไดเรกทอรีที่มี
hooks.jsonดังนั้น Hook จึงเริ่มต้นภายใน.agents/Wrapperbash -c 'if [ -x ./security_gate_hook.sh ] ...'จะจัดการทั้งกรณีดังกล่าวและการเปิดใช้งานจากรูทที่เก็บ จากนั้นสคริปต์จะcdเป็นgit rev-parse --show-toplevelก่อนที่จะทำงานใดๆ - สคริปต์จะตอบกลับใน stdout ด้วย JSON
{"decision": "allow"}ช่วยให้คำสั่งเดิมทำงานได้{"decision": "deny", "reason": "..."}จะบล็อกและแสดงเหตุผลให้ตัวแทนทราบ นอกจากนี้ เฟรมเวิร์กยังแสดงบูลีนallow_toolเพื่อให้เข้ากันได้กับสัญญาฮุกที่เก่ากว่า - ฮุกจะทำงานพร้อมกันและบล็อกลูปของ Agent จนกว่าจะทำงานเสร็จหรือถึง
timeout(เป็นวินาที ค่าเริ่มต้นคือ 30 หากละเว้น)
-i.bak รูปแบบนี้ใช้ได้กับทั้ง GNU และ BSD (macOS) sed:
sed -i.bak 's/"timeout": 120/"timeout": 900/' .agents/hooks.json && rm .agents/hooks.json.bak
7. วิธีการทำงานของตะขอเกี่ยวประตูรักษาความปลอดภัย
security_gate_hook.sh เป็นจุดแรกเข้าแบบบางที่ดึงข้อมูล 3 โมดูลจาก .agents/lib/ ดังนี้
โมดูล | บทบาท |
| ค่าเริ่มต้นของการกำหนดค่า, เอาต์พุต |
| ระยะที่ 1 การสแกนเชิงกำหนด (ไม่บังคับ) ด้วย Semgrep ข้ามหาก |
| ระยะที่ 2 การสแกนเชิงความหมายด้วย |
ขั้นตอนที่ 1: ตัดสินใจว่านี่เป็นการพุชหรือไม่
จุดแรกเข้าจะดึงคำสั่งจากเพย์โหลด stdin และทดสอบกับนิพจน์ทั่วไปที่จดจำ git push ในรูปแบบทั่วไป (git -C /repo push, cd x && git push, sudo git push) โดยไม่สนใจข้อความที่ยกมา เช่น git commit -m "before git push" อนุญาตให้ดำเนินการต่อไปนี้ได้ทันทีโดยไม่ต้องพุช
CMD_TO_CHECK=$(printf '%s\n' "$STDIN_INPUT" | jq -r '
.toolCall?.args?.CommandLine? //
.toolCall?.args?.command? //
.tool_input?.command? //
.CommandLine? //
.command? //
empty
')
...
if ! is_git_push_command "$CMD_TO_CHECK"; then
allow
fi
ขั้นตอนที่ 2: เลือกเครื่องสแกนเนอร์
SECURITY_GATE_SCANNER เลือกไปป์ไลน์ ค่าเริ่มต้น auto จะเรียกใช้ Semgrep และ CodeMender ที่ติดตั้งไว้ตามลำดับต่อไปนี้
case "$SCANNER" in
codemender|cm) run_codemender_gate false ;;
semgrep) run_semgrep_gate false ;;
auto|pipeline|"")
command -v semgrep >/dev/null && run_semgrep_gate true
command -v cm >/dev/null && run_codemender_gate true
allow ;;
esac
เมื่อระยะที่ 1 พบปัญหาการบล็อกในโหมดไปป์ไลน์ ระบบจะไม่ปฏิเสธด้วยตัวเอง แต่จะเขียนปัญหาลงในไฟล์ชั่วคราวที่ระยะที่ 2 เลือก เพื่อให้ CodeMender เป็นผู้ตัดสินขั้นสุดท้าย
ขั้นตอนที่ 3: ระยะ CodeMender
run_codemender_gate ใน engine_codemender.sh จะดำเนินการต่อไปนี้ตามลำดับ
- ค้นหาไฟล์ที่มีการเปลี่ยนแปลงด้วย
git diff --name-only origin/main(กลับไปใช้HEAD~1) หากไม่มีการเปลี่ยนแปลงหมายความว่าอนุญาต - สแกนแต่ละไฟล์ด้วย
cm find "$file" -y --bypass-warningจากนั้นดึงทุกอย่างกลับมาด้วยcm report --format jsonหากcm reportล้มเหลวหรือแสดงผล JSON ที่ไม่ถูกต้อง แสดงว่าเกิดข้อผิดพลาดในการสแกน ไม่ใช่ผลลัพธ์ที่ปลอดภัย - กรองเพื่อค้นหาผลการสืบค้นที่มีสถานะเป็น
OPENหรือREOPENEDและมีfile_pathที่ลงท้ายด้วยไฟล์ที่มีการเปลี่ยนแปลงไฟล์ใดไฟล์หนึ่ง ระบบจะไม่สนใจผลการตรวจพบที่คุณแก้ไขหรือปิดไปแล้วในข้อมูลเบื้องต้นเกี่ยวกับ CodeMender CLI - จัดประเภทการค้นพบแต่ละรายการ ความรุนแรงที่ระดับ
SECURITY_GATE_BLOCK_SEVERITYขึ้นไป (ค่าเริ่มต้นคือHIGH) จะเป็นการบล็อก ส่วนระดับที่ต่ำกว่านั้นจะเป็นการให้คำแนะนำ บันทึก และพิมพ์ แต่จะไม่หยุดการพุช - อนุญาตหากไม่มีสิ่งใดบล็อก หากผลการตรวจสอบที่บล็อกการพุชก่อนหน้านี้หายไปแล้ว เกตเวย์จะบันทึกเป็น
FIXEDต่อท้ายข้อตกลงเป็นCONTEXT.mdในส่วน## 4. Continuous Evolutionและคอมมิตการเปลี่ยนแปลงนั้น - นับจำนวนครั้งที่พยายามต่อการค้นพบการบล็อกโดยการอ่านบันทึกการตรวจสอบของตัวเอง การปฏิเสธแต่ละครั้งจะนับเป็นความพยายาม 1 ครั้ง ในการพยายามครั้งที่ 1 ถึง
SECURITY_GATE_MAX_RETRIES(ค่าเริ่มต้นคือ 3) เกตจะบันทึกDENIED_TO_AGENTและเพิ่มสิ่งที่พบลงในข้อความปฏิเสธ - ส่งต่อหลังจากใช้งบประมาณแล้ว ในการพยายามครั้งที่ 4 สำหรับการค้นพบเดียวกัน เกตจะทำงาน
cm verifyหากไม่สามารถใช้ประโยชน์จากสิ่งที่พบได้ (รหัสออก 1 หรือสถานะDISMISSED) ระบบจะดาวน์เกรดเป็นคำแนะนำ หากยืนยันแล้ว หรือcm verifyขัดข้อง เกตเวย์จะบันทึกBLOCKEDและปฏิเสธพร้อมคำขอให้เจ้าหน้าที่ตรวจสอบ - ปฏิเสธพร้อมคำแนะนำ หากผลการตรวจสอบยังคงดำเนินการได้ เกตจะแสดงเหตุผลนี้แก่ Agent
Security Gate blocked push (1 unresolved finding(s)).
Action Required: Execute the Secure TDD Loop sequentially for each finding:
For each finding below (one at a time):
1. Invoke 'security-test-writer' to author one failing boundary test in tests/ (assert RED).
2. Invoke 'defensive-developer' to apply the minimal defensive fix (assert GREEN).
3. Run the local test to confirm it passes before moving to the next finding.
Once all findings are resolved, run the full regression test suite (python3 -m unittest discover -s tests) and retry 'git push'.
Open Findings:
- [80bdddd6-...] (CRITICAL) in /home/you/codemender-lab/sample_app/data_service.py (Attempt 1/3): OS Command Injection in ping_host endpoint
นี่คือการส่งต่อระหว่างฮุกกับทักษะ ฮุกไม่ได้เรียก cm fix โดยจะระบุทักษะที่ Agent ควรใช้ จากนั้น Agent จะทำการแก้ไขแบบทดสอบก่อน และ git push ถัดไปจะเรียกใช้เกตอีกครั้ง
ข้อมูลอ้างอิงการกำหนดค่า
การตั้งค่าทั้งหมดเป็นตัวแปรสภาพแวดล้อมที่มีค่าเริ่มต้นที่ตั้งไว้ใน gate_common.sh ดังนี้
ตัวแปร | ค่าเริ่มต้น | เอฟเฟ็กต์ |
|
|
|
|
| ความรุนแรงต่ำสุดที่บล็อก |
|
| การปฏิเสธต่อการค้นพบก่อนที่จะปรึกษา |
|
|
|
|
| คำสั่งทดสอบที่ยกมาในพรอมต์การปฏิเสธและข้อความคอมมิต |
|
| เพิ่มรูปแบบที่ยืนยันแล้วต่อท้าย |
|
| บันทึกการตรวจสอบแบบต่อท้ายเท่านั้น |
| (ว่าง) | คำสั่งที่ไม่บังคับซึ่งรับเหตุการณ์เกตแต่ละรายการเป็น JSON ใน stdin |
8. การตรวจสอบ Hook แบบออฟไลน์
ก่อนที่เกตเวย์จะแตะ cm จริง ให้ยืนยันว่าเกตเวย์ทำงานอย่างถูกต้องด้วยการจำลอง เฟรมเวิร์กจะจัดส่งโปรแกรมทดสอบอัตโนมัติพร้อมไบนารี cm และ semgrep ปลอมที่ครอบคลุมเส้นทางอนุญาต คำแนะนำ ปฏิเสธ ข้อผิดพลาด และการส่งต่อ
bash .agents/tests/run_tests.sh
การเรียกใช้จะใช้เวลา 2-3 วินาทีและสิ้นสุดด้วยข้อความต่อไปนี้
-- test_pipeline_tools_missing_passes_smoothly
-- test_skills_frontmatter_valid
60 passed, 0 failed
การทดสอบครั้งสุดท้ายยังตรวจสอบ Frontmatter ของทุกทักษะใน .agents/skills/ ด้วย ดังนั้นนี่คือคำสั่งให้เรียกใช้อีกครั้งหลังจากแก้ไข SKILL.md
ถัดไป ให้จำลองสิ่งที่ Antigravity ส่งสำหรับคำสั่งที่ไม่ใช่การพุช สคริปต์ควรตอบ allow โดยไม่ต้องแตะเครื่องสแกนใดๆ ดังนี้
echo '{"toolCall":{"name":"run_command","args":{"CommandLine":"git status"}}}' \
| bash .agents/security_gate_hook.sh
{"allow_tool": true, "decision": "allow"}
ตอนนี้ให้จำลองการพุชโดยไม่มีการเปลี่ยนแปลงในเครื่องเทียบกับ origin/main เนื่องจากยังไม่มีรีโมต เกตจึงกลับไปใช้ HEAD~1 และสแกนไฟล์จากคอมมิตล่าสุดของคุณ หากต้องการให้ขั้นตอนนี้เป็นแบบออฟไลน์ ให้ชี้ไปที่ cm และ semgrep จำลอง ดังนี้
echo '{"toolCall":{"name":"run_command","args":{"CommandLine":"git push origin main"}}}' \
| PATH="$PWD/.agents/tests/mocks:$PATH" bash .agents/security_gate_hook.sh
Stage 1: Running Deterministic AST Scan (semgrep) on: sample_app/data_service.py ...
Deterministic scan clean. No AST vulnerabilities found.
Stage 2: Running Semantic Analysis & Verification (CodeMender)...
No blocking vulnerabilities detected. Code verified clean.
{"allow_tool": true, "decision": "allow"}
ทั้ง 2 ขั้นตอนทำงานเนื่องจากไดเรกทอรีจำลองมี semgrep ปลอมและ cm ปลอม ข้อความความคืบหน้าจะส่งไปยัง stderr และมีเพียงการตัดสินใจ JSON เท่านั้นที่จะส่งไปยัง stdout ซึ่งช่วยให้ Antigravity แยกวิเคราะห์ผลลัพธ์ได้
สุดท้าย ให้คอมมิตไฟล์เฟรมเวิร์กเพื่อให้ไฟล์เหล่านั้นเดินทางไปพร้อมกับที่เก็บข้อมูล
git add -A && git commit -m "Add Secure TDD skills, rule, and security gate hook"
9. กำลังเปิด Workspace ใน Antigravity
เปิด ~/codemender-lab เป็นโฟลเดอร์ใน Antigravity เมื่อโหลดแล้ว Agent จะมีสิ่งต่อไปนี้
- กฎ
secure_tdd_workflowในทุกเทิร์น - ทักษะทั้ง 6 รายการพร้อมให้รับชมแบบออนดีมานด์
- ฮุก
security-gateลงทะเบียนเมื่อrun_command
วิธีที่รวดเร็วในการยืนยันว่าทักษะต่างๆ ปรากฏขึ้นคือการถาม Agent ในการสนทนาใหม่ว่า "คุณมีทักษะ Workspace ใดบ้าง และแต่ละทักษะทำอะไรได้บ้าง" โดยควรระบุชื่อทั้ง 6 รายการ
สิทธิ์
Antigravity เป็นผู้เปิดใช้ Hook เอง ไม่ใช่ Agent ดังนั้นจึงไม่ผ่านข้อความแจ้งสิทธิ์ของเครื่องมือ แต่คำสั่งของ Agent เองจะทำ ในระหว่าง Codelab ถัดไป คุณจะเห็นข้อความแจ้งการอนุมัติสำหรับคำสั่งทดสอบ การดำเนินการ git และคำสั่ง cm ที่ Agent ตัดสินใจเรียกใช้โดยตรง อนุมัติเมื่อระบบถาม หาก Antigravity เสนอให้จดจำการตัดสินใจสำหรับคำสั่งที่มีคำนำหน้า การยอมรับจะช่วยหลีกเลี่ยงการแจ้งเตือนซ้ำๆ ตลอดทั้งลูป
สิ่งที่จะเกิดขึ้นในวันที่ git push
- Agent จะเรียกใช้เครื่องมือเทอร์มินัลด้วย
git push origin main - Antigravity จะจับคู่
run_commandกับhooks.jsonและเรียกใช้security_gate_hook.shด้วยการเรียกใช้เครื่องมือใน stdin - สคริปต์จะจดจำการพุช ค้นหาไฟล์ที่มีการเปลี่ยนแปลง สแกนไฟล์ด้วย
cm findและอ่านcm report - หากไม่มีสิ่งใดบล็อก ระบบจะพิมพ์
{"decision": "allow"}และดำเนินการพุชต่อ - หากการค้นพบบล็อก ระบบจะพิมพ์
{"decision": "deny", "reason": "..."}การพุชไม่ทำงาน Agent จะเห็นสาเหตุ และกฎที่เปิดตลอดเวลาบวกกับทักษะที่ตั้งชื่อไว้จะบอก Agent ว่าต้องทำอะไรต่อไป นั่นคือ การทดสอบที่ล้มเหลว 1 รายการ การแก้ไขขั้นต่ำ 1 รายการ เรียกใช้ชุดโปรแกรมอีกครั้ง และพุชอีกครั้ง
ยินดีด้วย คุณได้ทำ Codelab เกี่ยวกับทักษะและฮุกของ CodeMender สำหรับ Antigravity เสร็จสมบูรณ์แล้ว ใน Codelab ถัดไป คุณจะส่งคำขอฟีเจอร์ให้ Agent และดูการทำงานของลูปนี้ตั้งแต่ต้นจนจบ ตั้งแต่โมเดลภัยคุกคามไปจนถึงการพุชที่ผ่านเกต